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EDITOR'S NOTE 



CAROUNE ROSE 


The nerd market has been saturated — you all have computers — but what about the 
‘Tome market”? Vm no expert on this, but now that IVe taken on the persona of 
home user myself, I feel better qualified to say why normal people would rather use 
calculators and play hoard games. I recendy upgraded to a Power Mac 8500 so that I 
could work at home and also to be able to enjoy some fun software like the newly 
released electronic version of my favorite board game. Rather than just download 
software from an Apple server to use for work, I was going to buy soniediing to piay 
with to help justify my new expensive hardware purchase — just like any Mom, Pop, 
or kid might do. 

I took a trip — several, actually —^ to a bam-like emporium that is Nerd Central in 
my neighborhood but a singularly unpleasant place for non-geeks. (The clerks seem to 
know that if you have to ask for what you need, you don’t belong there, so they ignore 
you.) The first few times, I was dismayed to find that the game I wanted had been 
released only for Window^s and not yet for Macintosh. Finally, when I looked more 
closely at the product in the Windows .software section, I saw the small print on it that 
said ‘‘Wndows and Mac.” Then all I had to do was wait a half hour in line to buy it. 


Remember the big furor over wasteful packaging when CDs started replacing record 
albums in audio stores? Before long the shelves were redesigned and the extra 
packaging eliminated, V\Tat did 1 find in this big box containing a software product 
for which I had shelled out 50-plus dollars? Nodiing hut a CD in its case and a huge 
piece of molded black plastic cleverly designed to take up all the rest of the space in 
die box, I w^ondered how much that extra packaging had cn.st me, hut decided to get 
on with it and chill out over a good game. 


ni run out of space before I can get through all the other prol^lems 1 encountered. 
Suffice it to say I was dissatisfied w ith die product, ttj the point where T w'ould not 
have purchased it had I know n of its shortcomings ahead of time. It paled in 
comparison to a similar sharew'are game Fd been using (for which, needless to say, 

I didn’t have to drive to a store, search for the product, w^ait in line, spend a lot of 
money, and throw' away most of the package). 

The home market won’t really take off until the experience of purchasing softw^are 
becomes more pleasurable and foolproof, ITis could mean something more like 
buying audio CDs, where you go to a cool store organized by content type and not 
hardware type, where you can easily return the product within a short time for any 
reason, and wTere you can even out the disc before buying it. Or it may mean 
w^aiting till the practice of buying software off the Web has taken hold — especially 
inexpensive sharew^are, so that satisfaction is guaranteed in advance. Only solutions 
like these will roust the home market. Otherwise it’s just too much of a pain. 

— 

Caroline Rose 

Editor 


CAROLINE ROSE [crose@upp!e.com) isni □ 
typical home user, since she was one of the first 
people to use a Macintosh ond she cut her teeth 
before that on o timesharing system. But that was 
oil in the line of duty, whereas at leisure she uses 
computers os little os possible. She's even been 


known to hondwrife letters to friends. Speaking of 
which, Caroline has received so little moll from 
devsiop readers lately that this issue is missing a 
Letters section and she's missing hearing from 
you. What's on your mind about develops Please 
take o moment to let Caroline know." 


2 


deve/ap issue 2“? Morch 1997 










Looking to complete the set? 



V’K prKwit's 

rail 

ikH w'f' 

Ml 

fmiii tfccir 4ets 
tn ttwjw potciitijl ttMliuiikcrh; 

HJ 

neprcsentiftkin 4nd 4“nmpnina4c 
tih; 4iit? w itu; 

.\rrlijap1iijn*a tjutt:!!! !™ 

irtlnrTtpnrinjn 

ri^ii»r4s:-in iHc 4t>rtii dd 


If youVe looldtig for a complete develop collection, fiill-color, iKJiuid (x)pies are 
available for $13 per issue, including shipping and handling. (Back issues are also 
on the develop Boohmrk CD and the Deueioper CD Series Reference Library edition, 
as well as on the Internet) For more ijifomiarion about how' to order printed back 
issues (and where to find them online), see the inside front cover of this issue. 
Supplies are limited. Please ailoop 4 to 6 weeks for delivery. 


bsue 1 Color; Palette Manager; Offrcreen Worlds; 
PostScript; System 7; Debugging Deciaiation ROMs 

Issue 2 C++ (Objects; Style Guide); Object Pascal; 
Memory Manager; MacApp; Object-Based Design 

Issue 3 ISO 9660 and High Sierra; Accessing CD Audio 
Tracks; Comm Toolbox; 8*24 GC Card; PrGencral 

Issue 4 Device Driver in C++; Polymorphism in C++; 
A/ROSE; PostScript; Apple IlGS Printer Driver 

Issue 5 (Volume 2, Issue 1 ] Asynchronous Background 
Networking; Palette Alanager; Macintosh Common Lisp 

Issue 6 Til reads; CopyBits; MacTCT Cookbook 

Issue 7 QuickTime 1 X); TrueType; Thi’cads and Futures; 
C++ Objects in a World of Exceptions 

Issue 8 Curves in QuickDraw; Date and Time Entty^ in 
MacApp; Debugging, I lybrid A|iplication.s for A/UX 

Issue 9 Color on 1 -Bit Devices; 'lextBox YouVe Always 
Wanted; Sound; Terminal Manager; Debugging Drivers 

Issue 10 Apple Event Objects; Emhancenients for die 
LaserWriter Font Utility; GWbrlds; The Optimal Palette 

Issue 11 /^synchronous Sound; Multibuffering Sounds; 
Exceptions; NetWork: Distributed Computing 

Issue 12 Components; lime Bases; Apple Event (Coding 
Through Objects; Globals in Standalone Code 

Issue 13 Asynchronous Routines; QuickTime and 
Components; Debugging Color Printing; DeviceLoop 

Issue 14 Localizable Applicanons; 3-D Rotation; 
Quicklime (Video Digitizing xMaking Better Movies) 

Issue 15 QuickDraw GX; Component Registration; 
Floating Windows; Working in the Third Dimension 

Issue 16 Making the Leap to PowerPC; PowerTalk; 
Drag and Drop From the Finder; Color Matching With 
QuickDraw CtX; International Number Formatting 


Issue 17 Newton Proto lemplates; PowerPC] (Standalone 
Code; Debugging); Tliread Manager; Window Zooming 

Issue 18 Apple Guide; Open Scripting Architecture; 
Graphics Speed on the Power Macintosh; Displaying 
Hierarchica] Lists; Preferences Files 

Issue 19 OpenDoc Part Handlers; PowerPC Memory^ 
Usage; Designing for the Powder Macintosh; QuickDraw 
GX (Printing; Bitmaps); Inheritance in Sexipts 

Issue 20 A()C]E; xMake Your Own Sound Components; 
Scripting the Finder; NetWare on PowerPC 

Issue 21 OpenDoc Graphics; Designing a Scripting 
Implementation; D}4an; Object-Oriented Hierarchical Lists 

Issue 22 QuickDraw^ 3D; Copland; PCI Device Drivers; 
Custom Color Search Procedures; I'he OpenDoc User 
Experience; Futures 

Issue 23 QuickTime Music ^Architecture; l^uiekDraw' 3D 
Getimetries; Internet Config, Multipane Dialogs; 
Document Synchronization; ColorSync IS) 

Issue 24 Speeding Up whose Clause Resolution; 
OpenDoc Storage; Sound; Alert Guidelines; Printing 
Faster With Data Com[>ression; The New^ Device Drivers 

Issue 25 QuickTime VR Movies From QuickDraw 3D; 
Fhckcr-Free Drawing With QuickDraw^ GX; NLJRB 
Curves; C++ Exceptions in C; Localized Strings for Newton 

Issue 26 Mac OS 8; (QuickTime Conferencing, OpenDoc 
and SOM Dynamic Inheritance; Adding Custom Data to 
QuickDraw 3D Objects; 64-Bit Integer Math on 680x0 

Issue 27 Speech Recognition Manager; OpenDoc Part 
Kinds; Apple Guide 21 Wtii OpenDoc; Mac OS 8 
Assistants; Game Controls for QuickDraw- 5D 

Issue 28 Coding Your Object Model for Adv'anced 
Scriptability; New QuickDraw 3D Geometries; QuickDraw 
GX Line Layout Bending the Rules; AlacApp Debugging 
Aids; Cliiropractic for Your JVIisaligned Data 





Easy 3D With the QuickDraw 3D Viewer 


Ever since QuickDraw 3D shipped in 1995, the QuickDraw 3D Viewer 
has made adding 3D support to your application easy. With QuickDraw 
3D version 1.5 we^ve enhanced the Viewer to make it even easier to 
use. We've improved the user inteiface, added support for Undo, and 
rolled in some new API calk. Here you'll learn, how to implement the 
Viewer to provide simple yet powerful 3D capabilities in your products. 



NICK THOMPSON 


The QuickDraw 3D Viewer provides a for you to add 3D support to your 
application without having to come to grips with the complexity of die whole 
QuickDraw 3D programming AI^L As described in “QuickDraw 3D: A New 
Dimension for Macintosh Graphics” in diiveiop Issue 22, full use of QuickDraw 3D 
requires you to undersiaiKl many things before you can get started; for example, you 
need to be able to set up data structures to hold not only the geometries being 
modeled but also the other elements of a scene, inclutling the lighting, the camera, 
and the draw^ context* But sometimes you just want to be able to display some 3D 
data in your application without having to write five pages of setup cock. 

If this situation sounds familiar to you, the \Tew^er is tai[or“niade for your application* 
You 11 learn all you need to know to be able to use it from reading this article and 
examining the accompanying sample applications. Sri 11, yon might want to read the 
article in Issue 22 as background and to get a sense {if bow you can use the Viewer in 
conjunction with the QuickDraw 3D shared library. 


ABOUT THE VIEWER 

The QuickDraw' 3D Viewer is a high-level shared library, available in both Macintosh 
and Windows versions, thatk .separate from the QuickDraw 3D shared library. With 
fewer calls than die full QuickDraw 3D API, the \lewer is a great place to start 
exploring QuickDraw 3D. By implementing the Viewer, you can enable users to view 
and have a basic level of interaction with 3D data in your application without having 
to call any QuickDraw 3D functions. When you need nuire power, you can always 
mix QuickDraw 3D calls with Viewer calls. 

I'he Viewer is ideal for applicatioos that might be described as traditional 2D 
applications, such as image database and page layout applications. For example, the 


NICK THOMPSON (nickt^opplexom) went last 
summer to New Orfeans, o city with o great 
public aquarium, with the rest of the QuickDraw 
3D team. He spent a lot of time looking at totally 
awesome products from other vendors ond 
drooling over the SGI Onyx Infinite Reality demo. 


He also spent time at the oquorium, feeding his 
fascination with the ocean ond its life forms, and 
brought two fish tonks back with him — one for 
his home ond another for his office. This woy, if 
he canT be in the surf he at least hos props for 
his fantasies about being there.® 
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image database Cumulus (from the German developer Canto Software GMbH) is a 
traditional 2D application that implements the Viewer to enable users to manipulate 
objects in 3D (see Figure 1 )* 
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Figure !• An example of Viewer use In the Cumulus image database 

The \3ewer gives your application considerable functionality for free. For example, 
the Macintosh version of the Viewer supports drag and drop of 3D data. /\nd the 
Viewer allows access to the view object (described in detail in the article in droelop 
Issue 22) so that you can add to your application the capability of changing the 
lighting, the camera angles and position, and other things such as the type of 
Tenderer being used. 

Implementing the Viewer in your application is simple. /\fter going over a few 
preliminaries, we’ll look in detail at two sample applications — one just a barc-bones 
framework for using the \^ewer, and the second a more elaborate appHcation that 
implements a fuller set of Viewer features. The source code for both programs 
accompanies this article on this issueV CD and d€z>eloph Web site. 

CHECKING THAT THE VIEWER IS INSTALLED 

Before you can use the Viewer, you need to make sure that it’s installed. There are 
two ways to do this on the Macintosh: you can use Gesta.It on System 7 or you can 
weak-link against the library and check to see if one of the \^ewer routines has been 
declared when you launch your application. 

You need to call Gestalt with the constant gestaltQD3DViewer, as shown in Listing 1. 
The routine IsQD3DViewerInstalled returns a Boolean indicating whether the Viewer 
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has been installed correcdy. The bit selector gestaltQD3DViewerAvailable can be 
used to test the appropriate bit of the response from Gestalt, 


Listing 1* Checking for the Viewer with Gestalt 

Boolean IsQD3DViewerInstalled() 

{ 

OSErr theErr ? 

long gesResponse; 

if (Gestalt(gestaltQD3DViewer, figesResponse) 1= noErr) 
return false; 
else 

return [gesResponse == gestaltQD3DVievferAvailable); 


The other method is to weak-link against the Viewer library and check the value of 
one of the Viewer routines against the constant kUnresolvedCFragSymboIAddress 
{defined in CodcFragments.h): 

if ( [ long)Q3ViewerKew 1= kUnresolvedCFragSyinbolAddress) { 

/* Call Viewer routines. */ 

} 

For more information on weak linking (also called soft importing), consult the 
documentation that came widt your development system. If you use this method, 
youll also need to include the file CodeFragTnents,h. 

DETERMINING THE VIEWER VERSION 

Version 1,5 of the Vewer introduces several new ^'\PI features not found in previous 
versions of the Viewer, If you want your application to he comparihle with [previous 
versions of the Viewer, you need to check the version by calling the new routine 
Q3ViewerGetVersion. Of course, before you can call this routine, youll need to test 
whether it’s been loaded along with the Viewer shared library by cheeking its address 
against the symbol kUnresolvedCTragSymboIAddress. If it hasn't been loaded, you 
can safely assume that the Viewer version is LO. 

Alternatively, you can check the address of each function you need to use against 
kUnresolvedCFragSymboIAddress, Listing 2 shows a routine to determine the 
Viewer version; this routine works with all versions of the Viewer library, 

A BARE-BONE5 FRAMEWORK FOR USING THE VIEWER 

Now let's take a look at one of the simplest possible applications we might write to 
enable someone to open and view QuickDrav^' 3D metafiles (files containing 3DMF 
data). Of course, this isn't a real Macintosh program — it opens only one document, 
it doesn’t respond to Apple events, it doesn’t present a menu bar, and the user can’t 
save changes made in the window- But it does demonstrate that with just five calls to 
the View'er library^ you can provide good support for 3DMF data in your application. 
We’re not going to cover anything but the QuickDraw^ 3D part of this application in 
any detail, but the source code is commented w^ell enough so that it should he clear 
how it works. 
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Listing 2. Checking the Viewer version number 

OSErr GetViewerVersion(unsigned long *ma]or, unsigned long *ininor) 

{ 

/* Version 1.0 of the QuickDraw 3D Viewer had no get version call, so 
see if the symbol for the API routine descriptor is loaded. */ 
if ((Boolean)Q3ViewerGetVersion == kDnresolvedCFragSymbolAddress) { 
*inajor = 1; 

*niinor = 0; 
return noErr; 

} 

else 

return Q3ViewerGetVersian(major, minor); 


THE WINDOW 

Figure 2 shows the window from our simple application, called BareBones3DApp. An 
instance of the Mew^er— a \iewer object — can occupy an entire window^ or it can 
occupy some smaller portion of a w^ndow^ In the c'ase of BareBones3DApp, the 
viewer object entirely fills die window. The viewer object consists of a controller scrip 
and a content area outlined with a drag border. 



ContenI area 


Drag border 


Controller strip 
Active button 


Figure 2, Window from BareBones3DApp 


• The controller htrip contains a number of buttons for manipulating the user’s 
point of view^ (that is, the view’s camera). Each of the buttons either performs 
a specific function, such as setting a particular camera for the view, or sets a 
mode that determines howMiser interactions are handled. The controller 
strip can also be hidden; in this case, a \dsual element known as a badge takes 
its place to indicate to the user that the image in die \%dndow represents a 3D 
model. The user can click on the badge to make the controller strip appear. 

* The content area (called the picture area in earlier documentation) is where the 
3DA1F data is drawm. Users can interact with the object drawTi in the content 
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area in one of several modes, the modes being selected by clicking one of the 
buttons in the controller strip* In the default mode that the window opens up 
in, users can change the camera angle by dragging across the object* 

* The “OpenDoc-style’’ drag border indicates that the viewer content area can 
initiate drags of 3DMF data. By dnigging on this border the user can drag 
the object displayed in the content area. If dragging into and out of die 
content area is enabled (as it is by default), the border will be highlighted 
when a drag is initiated to indicate that the content area can receive drops as 
well. 


The part of the window that contains the content area and the controller strip (if 
present) is the vieiverpane. As an alternative to having the viewer pane entirely fill the 
window, you can place the viewer pane in just part of the window, as showm in Figure 
3, This is useful for embedding a 3D picture in a document window. 



Figure 3. The viewer pane as part of a window 


In the controller strip, the active button is dravm to look as if ids been pressed. The 
buttons shown in Figures 2 and 3 are the default ones; you can hide those you don*t 
want, (jf make visible the one additional button that^s hidden by default, by setting 
flags that will he discussed shordy You can also hide or show the entire controller 
strip- you’ll see how" to tlo this later. 

The full set of available controller buttons is showm in Figure 4. Let s look at each in 
turn. 



The camera viewpoint htittm (called the camera angle Imttan in earlier 
documentarion) enables the user to view the displayed object from a 
different camera angle. Holding down the button c'auses a pop-up menu 
to appear, listing the predefined direction cameras as well as any 


3 develop Issi^e 29 March T 997 

























Camera 

viewpoint Rotate Move 



Distance Zoom Reset 


Figure 4, The full set of available controller buttons 


perspective (view angle aspect) cameras stored in the view hints of the 
3DMF data* If any such cameras have name attributes associated with 
diem in the data, the natiies are displayed in the pop-up menu; otherwise, 
the cameras are listed as “Camera #1,^ and so on. (The predefined direction 
catneras are calculated based on the front and top custom attributes if 
present in the 3DMF view hints; otherwise, theyVe calculated from the 
displayed oliject’s coordinate space.) 

^ The disi:ance button lets the user move the displayed object closer or 

^ j farther away. Clicking the distance button and then dragging downward 
in the content area moves the object closer. Dragging upward in the 
content area moves the object farther away. The Down Arrow and Up 
Arr(jw keys also move the object closer or farther away, respectively. 



The rotate button enables rotating an object. Clicking this button and then 
dragging in the coiiteiit area nitates die displayed object in die direction 
of the drag. MTe arrow keys rotate the object in die direction of the 
arrow. Wth version 1.5 of the Viewer library, you can use the Shift key to 
constrain the motion of tlie object as you rotate it. 



I'he zomn button enables the user to alter the field of view of the current 
camera, thereby ^.ooming in or out on the displayed object. After the 
zoom button is clicked, pressing the Up Arrow and Down Arrow keys 
zooms the object out and in. By default, this button isn’t displayed. 



The move button lets the user move an object. Clicking this button and 
then dragging in the content area moves the object to a new location. 
The arrow keys move the object in the direction of the arrow. 


j The reset hutton resets the camera angle and position to their initial 
Mil settings. 


THE BAStC CALLS 

As mentioned earlier, you can add support for 3DMF data with calls to just five 
routines in the Viewer shared library. These routines, described below, are the ones 
we use in BareBones3DApp, For more details on these calls, see the book 3D 
Graphks Frog^imnning With QukkDnm 3D. 

* Q3 ViewerNew'—- Creates a viewer object and attaches it to a previously 
createcl window, then returns a reference to die viewer object. You need to 
pass this reference to odier Viewer routines. 

• Q IViewerDispose — Disposes of the viewer object and associated storage. 
You’ll probably want to do this just before dosing and disposing of the 
window. 


EASY 3D WITH THE QUICKDRAW 3D VIEWER 9 






















• Q3Viewt;rSetFile — Loads a model into the viewer object from a previously 
opened 3DMF file. In our program we call StandardGetFile to obtain the 
details of the file to open and then open it with the File Manager, passing 
Q3ViewerSetFile the file reference the File Manager gave us. 

• Q3ViewerEvent — Gives the viewer object the opportunity to handle events, 
then returns a Boolean diat indicates whether the event was handled. 

• Q3 Viewer Draw — Draws the contents of a viewer objects rectangle in 
response to an update event. 

THE MAIN ROUTINE 

The main routine of BareBanes3DApp handles initialization of Macintosh managers, 
grows the heap to its maximum size, and checks to see if the QuickDraw 3D Viewer 
is installed. There must he at least 24K free in the application heap before a call to 
Q3 ViewerNew can succeed, so it^s important to call the Toolbox routine MaxApplZc^ne 
to grow the applicatitm heap to its maximum size at the start of die program. Otherudse^ 
the Viewer may detect (in error) that there’s not enough memory to run. 

The program then calls the Toolbox routine StandardGetFile to locate a 3DMF file 
to open and read. The selected file is t^pened, and a window is created. The routine 
to create a view^er object looks like this: 

TQ3Viever0bject Q3ViewerNew(CGrafPtr port, Rect *rect^ unsigned long flags); 

N(jtice that you need to pass in port, rectangle, aiitl Hags parameters. It’s possible to 
create an “empty” viewer object by passing in nil for the port parameter; you can then 
assign a port later wddi Q3VdewerSetPon. The flags parameter is used to set flags that 
control various aspects of the behavior of the view er object you create; these flags, 
along with the behavior that results when they’re set, are listed in lalde 1. The flags 
of an already created viewer object can be ehangetl with the Q3\dcw'erSetFlags routine. 


Table 1 . Flags that control aspects of the viewer object 


Flag 


Result when set 

The viewer object is octlve |can be manipulated). 

A badge is displayed in the viewer pone. This flag should be 
cleared when kQ3ViewerControllerVS$jble is set. 

The controller strip is visible. This Rag should be cleared when 
kQ3ViewerShowBadge is set, 

A one^pixel frame is drawn within the viewer pane. 

Dragging into and out of the viewer content area is disabled. 
Dragging into the viewer content area is disabled. 

Dragging out of the viewer content oreo is disabled. 

The camera viewpoint button in the controlfer strip is visible. 
The distance button in the controller strip is visible. 

The rotate button in the controller strip is visible. 

The zoom button in the controller strip is visible. 

The move button in the controlfer strip is visible. 

The reset button in the controller strip is visible, 

QSViewerWriteFSle and Q3ViewerWriteData write out 3DMF 
data in text mode 


Default- 

On 

Oft 


kQ3 Vi e werActi ve 
kQ3 Vi e werS h o wBo dg e 


kQ3 Vi e werControl lerVi s i b le 


On 


kQ3 Viewer D ra w F ra me 
kQ 3 V ie we rD ragg i n g Off 


Off 

Off 

Off 

OR 

On 

On 

On 

Off 

On 

On 

Off 


kQ3ViewerDragginglnOff 
k Q3 Vie we rDrag g i n g OutOtf 
kQ3 Vi ewerBu tton C a mera 


kQ3ViewerButtonTruck 
kQ3 Vi e werButton Orb it 
kQ3 Vi e werB utton Zoo in 
kQ3 Vi e werB u tton Do I ly 
kG3 Vi ewer B utton R eset 


kQ3ViewerOut putTextMode 


(continued on next page) 
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Table 1 . Flags Jhar control aspects of the viewer object (continued) 


Flag 

Result when set 

E>efaull- 

kQ3ViewerDragMode 

The viewer object responds only to drag and drop interaction, 
and can't be manfpuloted in any other way. A mouse-down in 
the content area will initiate o drag operation. 

Off 

kQ3 Vi e werDrowG rowBox 

The viewer object displays a size box in the fowenright corner. 

Off 

kQ3 Vi e werDro wD rag Border 

The viewer object displays a drag border around the perimeter 
of the content oreo. 

On 

kQ3 Vie werDefa u it 

Returns the viewer object to the default configuration. 



I'he flags kQ3ViewerButtonTruck, kQ3ViewcrButtQnOrbit^ kQ3ViewerBiJttanZoom, 
and kQ 3 Vi ewer Button Dr }lly can also be used with the Q3ViewerSetCurrentButtoo 
routine. Passing one of diese flags to diis routine sets the viewer object to the mode 
indicated by the button. If the button is visible in the controller strip, ids drawn to 
look as if ids been pressed, and the previously selected button is deselected. 

You can override the default drag-handling behaviar by attaching your own drag 
handler to the document window. You’ll want to do this if your application supports 
multiple viewer objects per window or if yoidre creating something where the default 
may get in the way of your programming model — for example, an OpenDoc part or 
a HyperCard XCMD. 

Listing 3 shows how we implement the main routine in C, Note that we place a 
reference to the viewer object in the window’s refCon field so tliat later in the 
program we can easily get the viewer object associated witli the window. 


Listing 3* The main routine from BareBones3DApp 


void main(void) 
i 

short 

SFTypeList 

St anda rdFi1eRep1y 

OSErr 

WindowPtr 

Hect 

TQ3Viewer0bject 


myHumTypes = 1, myReftJwn; 
myTypeList = { '3DMF^ >; 
mySFReply; 
theErr = noErr; 
myWind = nil; 

myRect - { 0, 0, kWindHeighti kWindWidth }; 
myViewer; 


/* Initialize all the needed managers. 

InitGraf((Ptr)sqd.thePort); InitFonts[); lnitWindows{); 
InitMenus(); TEInit (); InitDialogs((long)nil); 
InitGursor(); 


/* Expand the heap to maximum size. */ 

MaxApplZone{); 

/* We weak-linked against the Viewer. Now check that it's installed, */ 
if ((long)Q3ViewerNew 1= kUnresolvedCFragSymbolAddress) { 
StandardGetFile(nil, myNumTypes, myTypeList, fimySFReply); 

(continued on next page) 
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Listing 3. The main routine from BareBones3DApp (continued) 
if (mySFReply*sfGood) { 

theErr = FSpOpenDF(fiinySFReply.sfFile, fsRdPenn, SmyRefUmn); 

OffsetRect(fimyRect, 50, 50); 

myWind = NewCWindow(nil, SdnyRect, "\pViewerApp", true, 

documentProc, (WindowPtr)-1, true, OL); 
if (inyViewer = Q3ViewerRew( {CGrafPtr )myWind, SiiiyWind->portRect, 
kQ3ViewerDefault)} { 

/* If the viewer object isn’t nil, we created it OK. */ 
theErr = QSViewerUseFile(myViewer, myRefKum); 

SetWHe fCon{myWind, (long)myViewer}; 

MainEventLoop(); 

} 

} 

ExitToShell(); 


THE MAIN EVENT LOOP 

The main event Inop, shown in Listing T handles events uniil the window is closed. 
There ^are only twci ty^ies of event tliat well consider handling in tliis program: 
update and mouse-down events. In response to an update event we’ll need to call 
Q3ViewerDraw. Handling monse-down events is somewliat more coni[>lcx, since 
well need to determine where the mouse-down occurred. 


Listing 4. The main event loop from BareBones3DApp 


void MainEventLoop[void) 


WindowPtr 

Boolean 

TQ3ViewerObject 

OSErr 

RgnBandle 

Rect 

EventRecord 

GrafPtr 


myWiad; 
gotEvent; 
theViewer; 
theErr; 
tempRgn; 
dragRect; 
theEvent; 
savedPort; 


while {(myWind = FrontWindow()) 1 = nil) { 

gotEvent = WaitRextEvent(everyEvent, &theEvent, GetCaretTimef), 
nil); 

if (gotEvent) { 

switch {theEvent.what) { 
case updateEvt: 

myWind = {WindowPtr)theEvent.message; 

theViewer = {TQ3ViewerObject)GetWRefCon(myWind); 

BeginUpdate(myWind); 

theErr = Q3ViewerDraw(theViewer); 

EndUpdate [myWipxd); 
break; 

(continued on next page) 
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Listing 4. The main evenl^ loop from 8areBones3DApp (continued) 
case mouseDown: 

switch {FindWindow(theEvent,where, smyWind)} { 
case inGoAways 

theViewer = (TQBViewerObject )GetWRefCon(iayWind); 
theErr ^ Q3Viewe rDis po s e(theViewe r); 
DisposeWindow(myWind); 
break; 

case inContent: 

GetPort(fisavedPort); 

SetPort( {GrafPtr)JiiyWind); 

Q3ViewerEvent(theViewer, ttheEvent); 

SetPort{savedPort); 
break; 

case inDrag: 

tempRgn = GBtGrayl?:gn(); 
dr agEec t = (* * tempRgn),rgnSBo k ; 
DragWindow(niyWind, theEvent,where, sdragRect); 
break; 

} 

break; 

} 

SetPort(savedPort); 

} 

} 


• If the mouse-down was in the dose b(]X of the window, we need to dispose of 
the viewer object and the w iodow* In the main event loop, we check to see if 
therea window open for the application by caUing the Toolbox routine 
Front\^Tiidow; if there isn’t one open, the application quits, 

• If the mouse-down was in the content area of the window, we can pass the 
event record to the routine Q3ViewerI£vent to handle. For version 1.0,4 and 
earlier versions of QuickDraw 3 D, you also need to ensure that the port is 
set to the current window, as shown in Listing 4, for Q3ViewerEvent to 
work as expected. 

• If the mouse-down was in the tide bar of the window, we need to drag the 
window around tmtil the user releases the mouse button. Fortunately, there^s 
a Toolbox routine to do this — DragWndciw. Notice that we pass in the 
rectangle associated with the desktop region; this works well for the case 
where multiple monitors are attached to the computer. 


A FULL-FEATURED APPLICATION USING THE VIEWER 

Our second sample application, called FuJlFeatured3 DApp 3 goes much of the way 
tow^ard providing the kind of features that you'd expect in a real application* It also 
gives some examples of how to use the full QuickDraw 3D library in conjunction 
with the Viewer library. Multiple 3DMF documents can be opened and changes can 
be saved; Undo, Cut, Copy, and Paste are supported; the user can change the viewer 
background color and the renderer type; and you can show and hide the buttons in 
the controller strip and even the strip itself, Fni not going to show all of the code 
here, but Til cover the salient points of the application, starting with the basics and 
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A LOOK AT THE QUICKDRAW 3D VIEWER FOR WINDOWS 

BY JOHN LOUCH 


The QuickDraw 3D Viewer For Windows differs from its 
Macintosh cousin in a number of ways. In fact, from an 
API ond functional standpoint, the Windows Viewer 
differs from the Macintosh Viewer more than the Windows 
version of any other QuickDraw 3D component — 
including the QuickDraw 3D core library, QuickDraw 3D 
RAVE, the interactive renderer, and the 3D Viewer 
Controller — differs from the Macintosh version. Well 
look at these differences here. 

Most fundamentally, all routines ore renamed in the 
Windows Viewer to begin with "Q3WinViewer" instead 
of "Q3 Vi ewer," to prevent name-space collisions. The 
Windows Viewer is actually implemented as o Windows 
control window (similar to the common controls, like the 
hierarchical tree view, thot were included with Windows 
95). The Windows Viewer can be implemented with the 
QuickDraw 3D Viewer API or the standard Windows APL 

If the QuickDraw 3D Viewer is a Windows pop-up 
window, it can be Implemented using these few calls: 

• Q3 Win Vi ewer New (or the Win32 call Create Window, 
passing In the constant kQ3ViewerClassName) — 
Creates o viewer object 

• WM^SYSCOLORCHANGE and WM^SETFOCUS — 
The parent window must post these messages to the 
viewer window (using PostMessage or SendMessage) 
when it receives them. 

Because the Windows Viewer is o window class, you 
donT need to send it events or ask It to update or draw. 
Those functions are all handled automatically by the 
Windows windowing system, Of course, you can still call 
Q3WinViewerMouseDown/MouseUp/ContinueTracking 
at any time. 

The following flogs used by the Mocintosh Viewer don't 
apply to the Windows Viewer: kQ3ViewerDraggingOff, 
kQ 3 Vi ewe rD ra g Mod e, kQ 3 VI ewe rD ra wG ro wBo x, 
kQ3ViewerDrawDrag Border, kQ3ViewerDragg ingOutOff. 
Most of these flags relate to drag and drop; the Windows 
Viewer doesn't support dragging out of the viewer content 
area os the Macintosh Viewer does. The other flags relate 
to human interface differences between the two systems. 

The following Windows Viewer functions differ in some 
way from their Macintosh counterparts: 

• Q3WinViewerNew(FiWND window, const Rect *rect, 
unsigned long flogs) ^— Takes on HWND instead of a 


CGrafPtr. If the window parameter is NULL, a parentless 
pop-up window is created; otherwise, the viewer 
window created is owned by the HWND you pass in 
and is □ child window. The flags parameter is also a 
little different in Windows. You can add in any of the 
standard Windows wiridow-style flags (such as 
WS_CHILD) with bitwIseOR to affect the type of 
window that you get. 

• QSWInViewerUseFile and Q3WinVIewerWrifeFtle — 
Identical to their Macintosh counterparts except they 
require a Windows file handle; for example, 

Q 3 W i n Vi ewe rWr i te F i le (TQ 3 Vi ewe rO b j ect viewer, 
HANDLE fileHandle). 

• Q3WinViewerSetF!ags — The parameters for this 
function are the some as for the Macintosh version. The 
behavior is different when you set the flags that show 
or hide controller buttons |kQ 3 Viewer Button Com era, 
kQ3ViewerButtonTruck, and so on). On the Macintosh, 
you must force a redraw (with Q3VlewerDraw or 
Q3VIewerDrawControlStnp) after you change which 
buttons are shown. In Windows the redraw happens 
automatically Inside this call. 

• Q3WinVlBwerGetMinimumDImensions — The 
behavior of this function is different from that of the 
Macintosh function because the window has to be 
shown with a toolbar to calculate the minimum 
dimensions. 

• Q3WinViewerGetWindow — Returns the HWND of 
the viewer window and not the parent window. 

The following functions are new in the API for the 

Windows Viewer: 

• Q3WinViewerGetControlStrip -— Returns the HWND 
of the controller strip, which is an actual Windows 
toolbar common control. With this function you can get 
an HWND reference and then actuate on it with the 
Windows API. 

• QSWInViewerGetBitmap — Returns o 32-bit-deep 
bitmap of the current model associated with the viewer 
object. 

• Q3WinViewerGetViewer(HWND theWindow) — 
Returns the TQ3VIewerObiect that's associated with a 
window, if that window is a Viewer Window class. 

• Q3WinViewerSetWindow — Sets the window in 
which the viewer will draw. This function is almost 
identical to Q3 ViewerSetPort except for the semantic 
differences between platforms. 
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then showing how^ to impletnent the various Viewer features. Again, the code 
accompanying this article is well commented so you should have no probiem 
following what’s going on. 

Vm not going to show' you a sample application that uses the Windows Viewer, but 
you can get a good idea of how^ it differs from the jMacintosh Vewer by reading 
Look at the QuickDraw 3D Viewer for Windows,” 

THE BASICS 

The first thing we dr> is to define a simple structure to store the information we need 
for each 3DMF document. In a mt)re substantial application you could add fields here 
as required. Well need to store a reference to the viewer fibjeet and also some 
information about the file the model came from, so that we can implement the Save 
and Revert commands. The definition for this structure is as follow^s: 

typedef struct { 

TQ3View0rObject fViewer; /* reference to the viewer object */ 

FSSpec fFSSpec; /* reference to the file for the document */ 

} ViewerDocument, *ViewerDocumentPtr, **ViewerDocumentHdl; 

Wefre creating three new types here: a document record plus a pointer and a handle 
to that document record. In the sample code for this article we generally put the 
document-related information in a Macintosh handle and store this handle in the 
refCon field of that document’s window. That w^ay we can easily get at the information 
we need. As shown in Listing 5, creating a window' dien becomes a matter of creating 
the handle for die document record wjth NewHandfeClear (which zeros out the 
allocated handle), creating a window for the document with NewCWindow, creating 
a viewer object with Q3 ViewerNew' and associating die window' w'ith the viewer 
object, and finally staring the handle to the document in the window’s reR^on field 
with die handy utility function SetVTRefCon, 

SetVVTeR^on has a sister fiinction called GetVTleft!!on, and we’ll use this w'henever 
we need to get the viewer object associated with a window. Once we have a Window'Ptr 
reference to a window, getting the associated view'er object is a question of getting the 
value from the window’s refCon field, casting it to a MewerDocumentlldl, and getting 
the viewer object from the appropriate field. 

theViewerDocumentHdl = (ViewerDocuinentHdl)G 0 tWRefCon[theWindow); 
if (theViewerDocumentadl 1= NULL) { 

if ((theViewer = {**theViewerDocumentHdl).fViewer) 1= NULL) { 

,i. /* Your code to work with the viewer object */ 

} 

} 

The next few sections look at how' we use functions from the QuickDraw' 3D Viewer 
shared library to add cool features to our program. 

READING AND WRITING 3DMF FILES 

Reading files with the Q3ViewerUseFiIe routine is one way of getting 3DA'rF data 
into your viewer object, as we saw in Listing 3, There are other I/O routines we can 
use for writing to a file, and for reading from and writing to areas of memory, 

• Q3 ViewerUseData — Similar to Q3 ViewerUseFile, except that instead of a 
file reference it takes a pointer to 3DAIF data stored in memory and displays 
that data in a view^er object you create. 
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Listing 5. Creating a window 

WindowPtr DoCreateNewViewerWindow(unsigned char *windowNajne) 

{ 

WindowPtr theWindow; 

Rect myRect = { 0, 0, kWindHeight, kWindWidth }; 

TQ3ViewerObject layViewer? 

ViewerDocumentHdl myViewerDocument = HULL; 

h Create a document record to hold the data for this instance. 
myViewerDocument = 

(ViewerDocumentHdl)NewHandleClear(sizeof(ViewerDocument)); 

/* Ideally, we should stagger the rect* +/ 

OffsetRectfimyRect, 50, 50); 

theWindow = NewCWindow(NTJLL, smyRect, windowName, true, 
docmnentProc, (WindowPtr)-1, true, OL); 

/* Create the viewer object associated with this window, */ 
if ((myViewer = Q3ViewerHew((CGrafPtr)theWindow, 

&theWindow->portRect, kQ3ViewerDefaultJ) !- NULL) { 

/* Store a reference to the viewer object in the document 
structure. */ 

{ViewerDocument).fViewer = myViewer; 

/* Store a reference to the document structure in the refCon field 
of the window* */ 

SetWHefCon{theWindow, (long)iiiYViewerDocument); 

} 

else { 

/* Clean up any allocated storage and quit* */ 
it (myViewerDocument) 

DisposeHandle((Handle)myViewerDocument); 
if (theWindow 1= NULL) 

CloseWindow(theWindow); 
theWindow = NULL; 

} 

return theWindow; 


• Q3 ViewerWriteFile — Writes the data being displayed in a viewer object 
out to a file, including information about the v4ew. We’ll use this routine to 
iinplement our Save and Save As comjTiands. 

• Q3ViewerWritcData — Similar to Q3VicwerWriteFile, except that the data 
is written to an area of memory rather than a file. 

We store a reference to a file associated with tlie viewer doemuent in an FSSpec 
record in our document structure. This makes it a lot easier to deal with files. When 
we want to save a viewer document we can look at the FSSpec to get the file in which 
to save the document. If the FSSpec is blank, we know that the document has no file 
associated with it. When reading a file, we need to make siore tliat we store the 
FSSpec in our document structure, as Listing 6 illustrates. 







Listing 6, Reading 3DMF data from o file 


WindQwPtr HandleFileOperiItein(FSSpec *theFSSpec) 


OSErr 

short 

WindowPtr 


theError; 
theHef; 
thel^indow; 


TQ3ViewerObject theViewer; 

ViewerDocumentHdL theViewerDocumentfldl; 

/* Open the file. */ 

theError = FSpOpenDF(theFSSpec, fsRdPenn, StheRef); 
if (theError = noErr) { 

theWindow = DoCreateNewViewerWindow{theFSSpec->naine); 
if (theWindow NULL) { 
theViewerDocmnentHdl = 

(ViewerDocuiaentHdl )GetWRef Con (theWindow); 
if (theViewerDocomentHdl •= NULL) { 


if ((theViewer = (**theViewerDocumentHdl).fViewer) 
NULL] { 

{**theViewerDoctiinentHdl) .fFSSpec = *theFSSpec; 
theError = Q3ViewerUseFile(theViewer, theRef); 
/* Ignore error. */ 


} 

} 


} 

theError = FSClose(theRef); 
/* Ignore error. */ 


} 

return theWindow? 


> 


In this example we open the data fork of the file selected by the user (or passed in as 
part of an Apple event) with FSpOpenDF and create a window with the routine 
DoCreateNewViewerWndow, described earlier. We then store the reference to the 
file in the appropriate field of the document record and read in the 3DMF data with 
the routine Q3ViewerUseFiJe. 

Writing out 3DMF data is equally straightforward, as shown in Listing 7. We use the 
routine Q3 Viewer Write Data to write the 3DMF data to a pre\nously opened file. We 
use the FSSpec previously stashed in the document record to open the file, with the 
routine FSpOpenDE Naturally, the Save As and Revert commands c^n be handled in 
a similar way, allowing you to implement a standard File menu with all the commands 
usually found there. 

SUPPORTING THE CLIPBOARD 

The Clipboard enables users to copy data between windows in an application and 
between applications that support the same data format. For example, we might want 
to copy data between our sample application and the standard Macintosh Scrapbook, 
We can do this by supporting Cut, Copy, and Paste in our appheation. This is really 
easy to do with the Viewer, which supplies a number of utihty routines specifically for 
dealing with the Clipboard. 
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Listing 7, Writing 3DMF data to a file 

OSErr HandleFiieSaveItem{WindowPtr theWindow) 

{ 

OSErr theError ^ paramErr; 

short theRef? 

TQ3ViewerOb j ect theViewer ; 

StandardFileReply theSFReply; 

ViewerDocmnentHdl theViewerDocumentBdl ; 

FSSpec theFSSpec? 

/* This option can't be selected unless therein a front window. 

The option is diinmed in the routine AdjustMenus if there no 
window* */ 

if {thewindow 1= NULL) { /* sanity check 

theViewerDocumentBdl = (ViewerDocuMentHdl)GetWRefCon(theWindow)? 
if (theViewerDocuinentHdl 1= NULL) { 

theFSSpec = (theViewerDocuinentHdl )* fPSSpecj 
/* Open the file* 

theError = FSpOpenDFf&theFSSpec, fsWrPerm, &theRef); 
if (theError == noErr) { 

if {(theViewer = [ **theViewerDocuiTientHdl) * tViewer) 

NULL) { 

theError = Q3ViewerWriteFile(theViewer, (long)theRef)j 

) 

theError - FSClose(theRef); 

} 

} 

return theError? 

} 


• Q3ViewerCupy — Copies the contents of the viewer object to the desk scrap 
in both 31 IMF and PICT binnats (the latter for applications that don't 
support 3 D data). 

• Q3 ViewerCat — Does the same thing as Q3ViewerCopyi but the content 
area of the viewer window is cleared. 

• Q3ViewerPaste — If the (Clipboard contains 3DMF data, replaces the data in 
the viewer object. 

• Q3 Viewer(]lear — Clears the content area of the viewer window and resets 
the default camera angle and position. This is effectively the same as “delete 
all” for the contents of the vdewer object. 

In addition, the y3ViewerUndo routine can help you support Undo for several Viewer 
operations. 

If your application has a standard Edit menu, handling events in this menu is simple 
given the routines described above. Listing 8 demonstrates how^ to use these routines. 
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Obviously for this to work correctly the Edit menu needs to be set up so that items 
are dimmed and showm appropriately — Copy makes no sense for an empty viewer 
object, and Paste makes no sense if there's no 3Di\lF data to paste. So w e need to do 








Listing 8. Usmg the Clipboard utility routines 

void HandleEditMenu(short menultero) 

{ 

ViewerDocuiaentHdl theV i ewer Doc umentBdl; 

WindowPtr theWindowj 

TQ3Viewer0bject theViewer? 

OSErr theError? 

theWindow = FrontWindow(); 

if (theWindow i= HULL) { 

/* Get the reference to our viewer document data structure 
from the reference constant for the window. Cast it to the 
appropriate type. If we can't get it (if it's NULL), bail. */ 

theViewerDocumentHdl == (ViewerDocumentHdl)GetWRefCon(theWindow); 

if (theViewerDocumentHdl NULL) 
return; 

/* Get the reference to our viewer object from our data 
structure. */ 

theViewer = (* * t heViewerDocument Hd1}.fViewe r; 

if (theViewer == NULL) 
return; 

switch (menuItem) { 
case iEditUndoItem: 

theError = QSViewerUndo(theViewer); 

QSViewerDrawContent(theViewer ); 
break; 

case iUditCutltem; 

theError = QSViewerCut(theViewer); 
break; 

case iEditCopyItem: 

theError - Q3ViewerCopy(theViewer); 
break; 

case iEditPasteltem: 

theError = Q3ViewerFaste{theViewer); 
break; 

case iEditClearltem: 

theError = Q3ViewerClear(theViewer); 
break; 

> 

} 


two things: check that there^s some content in the viewer object, and check that 
there^s something on the scrap that can be pasted. We do this with the routines 
Q3 ViewerGetState and GetScrap. We then enable or disable Cut, Copy, Clear, and 
Paste accordingly, as illustrated in Listing 9. This listing also shows how to set up the 
Undo menu item. 

SETTING THE VIEWER BACKGROUND COLOR 

You might want to let the user set the background color of the viewer — for example, 
to match the background color used for a multimedia presentation or to match the 
color of a Web page. We use the routine Q3ViewerSetBackgroundColor to do this, 
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Listing 9, Setting up the Edit menu 

/* Get the viewer state* We need to know if it's empty* */ 
theViewerState = Q3ViewerGetState(theViewer)j 


/* Adjust the Edit menu* 

theMenu = GetMHandle{mEditHenu); 

if {((theViewerState & kQ3ViewerHasUndo) { 

/* Undo is possible; get the string for this item and enable it* */ 
Boolean canUndo; 

/* Hokeyness alert; We pass in the address of the second element of 
the itemString array, allowing us to set the length later in the 
first element of the array, saving us the need to do an in-place 
C-to-Pascal string conversion (the Toolbox routines require a 
Pascal-format string that has the same length as the first byte). */ 
canUndo = Q3ViewerGetUndoString(theViewer, &itemstring[1], 
SitemStringLength); 

itemStringrO] ^ (char)itemStringLength; 

/* If we can undo, enable the new string; if not, use the default 
can't-undo string. */ 

if (canUndo == true itemStringLength > 0) { 

SetMenoItemText(theMenu, iEditUndoItem, 

(unsigned char *)itemstring); 

Enableltein( theMenu, iEditUndoItem); 

} 

else { 

GetIndString{(unsigned char +)itemString, 2233, 1); 

SetMenuItemText(theMenu, iEditUndoItem, 

(unsigned char *)itemString); 

Dis ableltem(theMenu, iEditUndoItem); 

} 

} 

else { Undo isn*t possible* */ 

GetIndString{(unsigned char *)itemString, 2223, 1); 

SetMenuItemText(theMenu, iEditUndoItem, (unsigned char *)itemString); 
DisableItern(theMenu, iEditUndoItem); 


if {((theViewerState & kQ3ViewerHasModel) { 
Enableltem(theMenu, iEditCutItem); 

E na b1eItern(the Menu, iEditC opyItern); 
Enableltem[theMenu, iEditClearltem); 

} 

else { 

Disableltem(theMenu, lEditCutltem); 
Disableltem(theMenu, iEditCopyltem); 

Dis able!tern(t heMenu, iE ditC1e arItern); 


(continued on next pagej 








Listing 9- Setting up the Edit menu (continued) 

/* Check that there's some data that we can paste, GetScrap returns a 
long that gives either the length of the requested type or a negative 
error code that indicates that no such type exists. */ 
tmpLong = GetScrap(nil, '3DMF', itheScrapOffset); 
if (tmpLong < 0} 

DisableItem(theHenu, iEditPasteltem ); 
else 

EnableItem(theMenu, iEditPasteltem )} 


but first some conversion of color component values is necessary. While Macintosh 
Toolbox routines tend to work with the RGB system of specifying color, tlie 
QuickDraw 3D routines use an /\RGB type that specifies an alpha channel 
component in addition to the red, green, and blue components. Conversion is 
necessaiy because each component of a QuickDraw 3D Ai-iGB specification is a float 
in the range 0 through 1 rather than a 32-bit integer ranging from 0 through 65535 
like the Macintosh Toolbox RGB components. See Listing 10 for the code chat does 
the conversion. 


Listing TO. Converting color component values 

RGBC o1o r t h eRGBCo1or; 

TQ3ColorARGB theViewerBGColor; 


Q3ViewerGetBackgroundColor(theViewer, &theViewerBGColor); 
theRGBColor.red - theViewerBGColor,r * 65535.0; 
theRGBGolor.green - theViewerBGColor.g * 65535,0; 
theRGBColor.blue ^ theViewerBGColor,b * 65535.0; 

if {PickViewerBackgroundColor(&theRGBColor, ''NpPick a viewer background 
color:")) { 

theViewerBGColor-a = 1; 

theViewerBGColor,r = theRGBColor.red / 65535.0; 
theViewerBGColor.g = theRGBColor.green / 65535,0; 
theViewerBGColor.b = theRGBColor.blue / 65535.0; 

Q 3 ViewerS et B ac kgroundC o1o r(t h eViewe r, & th eViewe rBGC olor); 


The routine Pick^TewerBackgroundColoiv based on a routine described in the book 
Advanced Color bnaging on the Mac OS, uses the Macintosh Color Picker component 
to quer}^ the user for a new background color, returning a Boolean indicating whether 
the user chose a new color* This routine, shown in Listing 11, is ^ good deal simpler 
than it looks at first glance* We pass in the current background color and the prompt 
to be displayed in the Color Picker dialog* Since the Color Picker can use die Edit 
menu to support copy and pasting of color information, we need to tell it where our 
Edit menu is and which items in the menu are which* We then set up a Color Picker 
info structure, before calling PickColor (the guts of this routine). If the user cancels, 
we set the return value accordingly and return. 
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Listing 11. Lefting the user choose a window background color 

Boolean PickViewerBackgroundColor(RGBColor *theRGBColor, 
unsigned char *thePrompt) 

{ 

GolorPickerlnfo cpinfo; 

Boolean returnValue = false; 

/* Set the input color. */ 

cpInfo.theColor.color.rgb.red = (*theRGBColor).red; 
cpinfo.theColor.color.rgb.blue = (*theRGBColor).blue; 
cpInfo.theColor.color.r gb,green = (* theRGBColor).gree n; 

cpinf 0 .theColor.profile = OL; 

cpinfo.dstProfile = OL; /# No ColorSync destination profile */ 
/* Set the Color Picker flags. */ 

cpinfo.flags = AppIsColorSyncAware [ CanModifyPalette | 
CanAnimatePalette; 

/* Center dialog box on the deepest color screen. */ 
cpinfo,place^^here - kOeepestColorScreen; 

cpInfo.pickerType - OL; /* System default picker */ 

/* Install event filter and color-changed functions. */ 
cpinfo.eventProc = nil; 
cpinfo,colorProc = nil; 
cpinfo.colorProcData = OL; 

/* Do a sanity check. */ 
if {thePromptI0] >= 255) 
theProiiipt[0] = 255; 


Bloc kMove(t heP rompt , cpIn f o.promp t, t he P rompt 101); 


Describe the Edit menu for the Color Picker Manager. 
cpinfo.mlnfo.editMenuID = mEditMenu; 
cpinfo.mlnfo.cutltem = iEditCutItem; 
cpinfo.niinfo.copyltem = iEditCopyltem; 
cplnfo.mlnfo.pasteltem “ iEditPasteltem; 
cplnfo.mlnfo.clearItem = iEditClearltem; 
cplnfo.mlnfo.undoltem - iEditUndoItem; 


/* Display a dialog box to allow the user to choose a color. */ 
if (PickColor(&cpInfo) == noErr cpinfo. newColorChosen) { 

/* Use this new color. */ 

(^theRGBColor).red = cpinfo.theColor.color.rgb.red; 

(* theRGBColor).blue = cpinfo.theColor.color.rgb.blue; 

(*theRGBColor).green = cpinfo.theColor.color.rgb.green; 
returnValue = cpinfo.newColorChosen; 

> 

return returnValue; 
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CHANGING THE RENDERER 

QuickDraw 3D ships with two basic renderers: a wireframe and an interactive Tenderer, 
as illustrated by the examples in Figure 5. 


flctiueflrt^" Funky Radio.3DMF 




Interactive Tenderer 

Figure 5. Drawing witd the interactive and wireframe renderers 


Wireframe Tenderer 


The Viewer shared library has no way to change the tenderer, but we can use 
lower-level QuickDraw' 3D routines to set the renderer and report the setting back 
to the user. 

The renderer is associated with a view object, and we must have a view object in 
order to draw' anything. The Viewer shared librar}' contains a routine that enables us 
to get at die view, called Q3\^ew'erGet\lew. 

Once we have the view oliject, w^e can start to extract informatiDn from it; in this case 
well need the renderer abject associated wdth the view (see Listing 12). 


HIDING AND SHOWING BUTTONS AND THE CONTROLLER STRIP 

As mentioned earlier, you can control w^hether a button is displayed in the controller 
strip by toggling the appropriate flag. For example, to toggle whedier the rotate 
button is displayed you can ase the following code, which gets the viewer flags and 
bitwise^manipulates them; 

theViewerFlags = Q3ViewerGetFlags(theViewer); 
theViewerFlags kQSViewerButtonOrbxt? 

Q3ViewerSetFlags(theViewer, theViewerFlags); 

Q3ViewerDraw(theViewer); 




You can display or hide ocher buttons in the same way by toggling the appropriate flag. 


EASY ao WITH THE QUICKDRAW 3D VIEWER ^3 















































Listing 12 . Setting Jhe Tenderer 
swit ch {menult em) { 

/* These two items appear in the Renderer submenu of the View menu- */ 
case iRendererWireframeltem: 

/* Get an instance of a wireframe renderer object. */ 
myRenderer = Q3Renderer_NewFromType(kQ3RendererTypeWireFrame); 
break; 

case iRendererInteractivelteni! 

/* Get an instance of an interactive renderer object, */ 
myRenderer = Q3Henderer__NewFromType(kQ3RendererTypeInteractive); 
break; 

) 

/* Set the renderer for the view, */ 
myView = Q3ViewerGetView(theViewer); 
if (myView \= NULL && myRenderer 1= NULL) { 

/* Set renderer to the one created in the switch statement above- */ 
myStatus Q3View_SetRenderer(myView, myRenderer); 

/* Dispose of the reference to the renderer* */ 
myStatus - Q30bject_Dispose(myRenderer); 

/* Redraw the content area of the viewer object. */ 
theError ^ Q3ViewerDraw(theViewer); 


Stnnetimes you don't wniu to see the controller sin|^ nt ulL When the strip is hidden, 
you can still indicate to users that the image represents n 3D model l)y displaying n 
badge, as shown in Figure 6. 



Figure 6. The 3D badge in a window with the confroller strip hidden 


24 ttevWop 29 March 1997 























The following code toggles the badge on and off: 

theViewerFlags kQ3ViewerShowBadge; 

theViewerFlags kQiViewerControllerVisible; 

Q3ViewerSetFlags(theViewer, theViewerFlags )} 

Q3ViewerDraw(theViewer); 

When the badge is displayed, the user can get the controlier strip by clicking on the 
badge* The badge and the controller strip are mutually exclusive — if the badge is 
displayed, the controller strip should be hidden, and vice versa* In addition, badge 
control is one-directional for the user — the user can only switch from badge inode 
to controller strip mode* It's the responsibility of the application to redisplay the 
badge at appropriate times l)y setting the viewer object's kQ3V]ew'erShowBadge flag 
again and clearing the kQ3 ViewerControllerVisible flag* For example, when a viewer 
object is ileselected in a compound document, the application may switch the viewer 
object hack to badge mode. 

RESIZING THE VIEWER PANE WITHIN THE WINDOW 

As mentinned earlier, the viewer pane can occupy tlie entire window or it can occupy 
just part of die window, as in a multi media product. The code to draw^ the viewer 
pane smaller than the window uses the routine Q3\^ewerSetBnunds to define the 
hounds of the view-er object. 

'Fhe code snippet in Listing 13 toggles the viewer pane between taking up the entire 
window and being inset a small amount. It keys off the kQ3 ViewerDrawTrame flag; if 
this flag is set, the pane is inset. 


Listing V3, Toggling the viewer pane between the entire window and just a part 

theTmpRect = theWindow->portRect; 

if (theViewerFlags & kQ3ViewerDrawFrame) 

Q3ViewerSetBounds(theViewer, &theTmpRect); 
else ( 

InsetRect(&theTmpRectp kInsetPixelsConst, klnsetPixelsConst); 
Q3ViewerSetBounds(theViewer, &theTmpRect); 

theViewerFlags kQ3ViewerDrawFrame; 

GetPort(& savedPort}; 

SetPort((GrafPtr)theWindow); 

EraseRect{stheWindow->portRect); 

SetPort(s avedPort); 


Listing 14 shows how to resize the entire window, ITere are a couple of nuances here. 
We use the routine Q3VlewerGetMinimumDimension to calculate the minimum 
vridtii and height of the wnndow^ before resizing it with the routine Size Window. The 
minimum width is variable and depends on the number of buttons that are currently 
visible in the viewer. We also need to cake into account the dimensions of the size box 
in the low^er-right comer of the window. We can then set the bounds of the viewer 
object with the function Q3ViewerSetBounds. 
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Listing 14. Resizing the entire window 


case inGrow: 

/* First we need to calculate the ininitnum size for this window. 
Fortunately, the Viewer library has a handy little utility 
function that we can use here. */ 
theErr = Q3ViewerGetMinijmumDiinension( theViewer, £ width, fitheight); 
growRect.top = height; 

growRect.left = width +34; /* +34 so the size box looks neat 

growRect.bottom = kMaxHeight; 
growRect,right = kMaxWidth; 

newSize = GrowWindow{theWindow, theEventRecord.where, &growRect); 
if {newSize != 0) { 

width = LoWrd(newSize); 
height = fliWrd(newSize); 

SizeWindow{theWindow, width, 

03ViewerSetBounds(theViewer, 

Q3ViewerDraw(theViewer); 

DoDr awG rowlc on(t h eWindow); 


height, true); 
&theWindow->portRect); 


} 

break; 


THE VIEW FROM HERE 

Implementing the QuickDraw 3D Viewer in your application is an inexpensive way 
to get your feet wet before taking the plunge into Quickl>ra\v 313, as youVe seen in 
this article. /\nd remeinher — your application can mix and match QuickDraw 3D 
Viewer roiitines with QuickDraw' 3D routines to exteiul the basic functionality of the 
View^er. So go ahead anti give your users a taste of 3D excitement. You may just 
decide that it’s worth impleincnting QuickDraw' 3D in lull in your next application. 


RELATED READING 

• ''QuickDraw 3D: A New Dimension for Mocinrosh Graphics" by Pablo Fernicola 
and Nick Thompson, develop Issue 22. 

• 3D Graphics Progromming With QuickDraw 3D by Apple Computer, Inc. 
(Addison-Wesley, 1995). 

• Advanced Color Imaging on the Woe 05 by Apple Computer, Inc. (Addison- 
Wesley, 1995). 
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supplied by Viewpoint, and the Funky Rodio data 
set is courtesy of Plastic Thought, Inc. Figure 1 is 
from the Canto Software GMbH Cumulus image 
database application with models from Model 
Masters and Viewpoint Data lobs." 
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THE OPENDOC 
ROAD 

Moking the Most 
of Memory in 
OpenDoc 


TROY GAUL AND 
VINCENT LO 

In Issue 28, we discussed how the OpenDoc Memory 
Manager works and how part editors manage Toolbox 
memory. This time well examine ways to use memory 
more efficiently in the OpenDoc environment. 

We’ll begin by talking about how to avoid memtiry 
leaks. Memory leaks, which can be a problem when 
developing traditional Macintosh applications, are as 
much a concern in OpenDoc. But because OpenDoc 
uses reference counting, there are a few extra things to 
pay attention to. We’ll also discuss how to handle 
parameters correctly to avoid memory leaks, and we’ll 
take a look at ways you can set up your part editor to 
maximize memo ry usage. 


AVOIDING MEMORY LEAKS 

OpenDoc objects and part editors use a reference- 
counting scheme that enables OpenDoc to keep track 
of which objects are in use. Each time a client acquires 
an object (through the object^ Acquire method), the 
object’s reference count is incremented by 1. When the 
oltject is no longer being used, the client releases it (by 
calling the object’s Release metliod) and its reference 
count is decremented. The object’s reference count 
indicates how many references to the object are being 
held by clients. When the reference count goes down 
to 0, the object can be destroyed without affecting any 
other objects. For more information on how^ reference 
counting works in OpenDoc, see the OpenDoc Road 
column in develop Issue 27, “Facilitating Part Editor 
Unloading.’^ 


result, a memory leak occurs because the occupied 
memory can’t be used during the se.ssion. 

To avoid reference cc^unt errors, it helps to keep in 
mind which classes are reference-counted and which 
methods affect an object’s reference count. OpenDoc 
uses reference counting on classes whose objects often 
have more than one client. These classes are subclasses 
of ODRefCntObject, and many are classes that part 
editors interact with directly. 

In general, if a method nante starts with “Acquire,” the 
reference count of the object named in the method is 
incremented wiien the method is called. When the object 
is no longer needed, the caller should release it. For 
example, if a part editor calls ODDraft::AcquireFrame 
to access a frame object, the reference count of the 
returned frame object is incremented. After the editor 
is done using the ft'ame reference, a call to the object’s 
Release method (ODFrame::Release) must be made to 
avoid a memory leak. 

Some methods return a reference-counted object 
witliout affecting the object’s reference count. These 
methods usually start with “Get.” For example, 
ODFacetcGeth'rame returns the frame object with 
which the facet is associated without incrementing the 
reference count of the frame object. In this case, the 
caller shouldn’t call ODFramecRelease. Typically, a 
Get method is used to return an invariant or unchanged 
attribute of an object. In the case of ODFacet, the facet 
acquires and stores a reference to its ODFrame (object. 
This reference isn’t released until the ODFacet object 
is deleted. WTien ODFacetcGetFrame is called, 
ODFacet returns the stored reference to the caller. 
Since this reference remains valid until the ODFacet is 
deleted, you can use it as long as the ODFacet is a valid 
object. If you want to u.se the returned ODFrame 
object beyond the ODFacet’s lifetime, you should call 
Acquire on the ODFrame to ensure that you have a 
valid reference to it. 

The best way to avoid reference count errors is to 
familiarize yourself with the OpenDoc API and 
understand how it affects an object’s reference count. 
The OpenDoc Class Reference provides a detailed 
description of reference counting for each metliod. 


If the acquired object doesn’t get released when it 
should, the reference count doesn’t go to 0 and the 
object remains in memory until the session ends. As a 


Temporary objects to the rescue. The code for 
acquiring a reference-counted object for a brief period 
of time and then releasing it turns out to be quite 


TROY GAUL (rgoul@apple.com] recently joined the OpenDoc 
engineering team, where he's working with Java™. Having also 
written the sample part editor formerly known as Cappuccino, he 
has a caffeine buzz that should last into the next century. * 


VINCENT LO (vincent@apple.com) is Apple's technical lead for 
OpenDoc. Since he recently introduced the OpenDoc team to Hong 
Kong cinema, it occasionally happens thot the OpenDoc engineering 
meeting resembles o scene from a Hong Kong action movie.* 
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complicated. Listing 1 shows how complicated it can be 
to handle a reference-counted object when using 
exception-handling code. 


Listing 1. Handling reference<ounted objects 

ODFrame* fraine = kODNULL; 

ODVolatile(frame); 

// Make sure that the frame can be used in 
// the CATCH block, 

SOM^TRY 

// Acquire the frame* 

frame = draft“>AcquireFrame(ev, id)? 

// Do something with the frame here, 

// Release it when done, 
frame->Release(ev ); 

SOM_CATCH_ALL 
if (frame) 

frame->Release(ev); 

SQM ENDTRY 


To help alleviate this problem, Openl^oc provides a 
utility librar)' that uses stack-based C++ objects to wrap 
references to Open Doc reference-counted objects* 
These C++ objects are called temporary objects. WTienever 
such a C++ object goes out of scope, its destructor is 
called and releases the reference-counted object. 

The code Iragment shown in Listing 2 does the same 
thing as the example in Listing 1 but uses temporan' 
objects instead* This code is simpler and less error^ 
prone. 


Listing 2, Easier handling of reference'Counted objects 
SOM_TRY 

TempODFrame frame = 

draft->AcquireFrame(ev, id); 

//Do something with the frame here* 


SOM_CATCH_ALL 
SOM ENDTRY 


The OpenDoc utility library pro\ides temporary objects 
for 17 reference-counted classes, including ODPart, 
ODFrame, ODExtension, and ODStorageUnit* For 
more information on creating temporary objects, see 
the “Temporary Objects” section of Appendix A in the 
OpenDoc Cookbook. 


The OpenDoc utility library also provides temporary 
objects for objects that areu^t reference-counted, such 
as ODByteArray and ODIText. These OpenDoc ty^es 
deserve special attention in regard to memory usage. 

The ODByteArray stmciaire contains three fields: 
_buffer, _maximum, and _length. The _buffer field 
points to a memory block whose size is indicated by the 
_maximmn field. Jength is the number of bytes used; 
it has to be less than or equal to the value of _maximum. 

Generally, ODByteArray is used instead of a raw pointer 
because the size of the memory block is included. This 
enables SOM and OpenDoc to pass data between 
processes without relying on shared menior)'. But 
because the _buflfer field is hidden in the ODByteArray, 
the memory block can easily be forgotten. Failing to 
free this memory block when an ODByteArray is 
deallocated creates a memory leak* 

The ODIText structure stores a user-visible string* One 
of its fields contains the string's format; the other is an 
ODB)'teArray tliat contains die text string. The memory 
block in the f )DB)1:eArray needs to be freed when the 
ODIText structure is deallocated* 

Handling in and out parameters. Memory leaks can 
also occur when parameters aren't handled correctly. In 
an OpenDoc methctd, each parameter is designated as 
in, out, or inout. 

• *'\n in parameter passes data from the caller to the 
cal lee. 

• An out parameter transfers data from the callee to 
the caller. A method's result also acts as an out 
parameter 

• An inout parameter passes data from the caller to 
the callee, wLich can then modify it and pass it back* 

To determine a particular parameter’s designation, you 
can check die “.idl” files, or see the OpenDoc Cl/iss 
Reference for detailed information on each parameter. 

The parameter's designation defines the memory 
responsibility of the caller and callee. The part editor 
can use memory on the stack for parameters of 
primitive tyq>es or fixed-size data structures. But for 
strings, byte array buffers, and objects, the part editor 
must use the OpenDoc Memory Manager to do the 
following: 

• allocate and deallocate memory for in and inout 
parameters passed to an OpenDoc object 

• deallocate memory for out parameters retumed 
from an OpenDoc object 
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• allocate memory for out parameters returned from 
the part editor’s methods 

If a part editor calls an OpenDoc method and doesn’t 
deallocate the out parameter^ the memor)^ won’t be 
freed lindl the session ends, causing a memor)" leak. 

Since it’s impossible to know how a piece of memory is 
allocated, OpenDoc and part editors have to use the 
OpenDoc Memory Manager as the common memory 
management facility. This is the only way to ensure 
that memory allocated by OpenDoc can be freed by the 
part editor and vice versa. 

SETTING UP YOUR PART EDITOR 

Because your part editor is used in documents with other 
part editors as users construct compound documents, 
it’s important to tnake the best use of memory* Let’s 
talk about some of the things you can do to minimize 
memory usage. 

Keep the data section small. MTen creating a part 
(which is a shared library), the linker will generate code 
and data sections. The code section contains the 
instnicdons that make up your part editor. This section 
is read-only because it’s file-mapped onto read-only 
memory when virtual memoty is in use. The data section 
is stored separately because it needs to be writeable; it 
contains globals, static variables, transition vectors, 
virtual tables, and so on. 

A single in-memory or memory-mapped copy of the 
code section is shared by all processes in which that 
code is used. The data section is handled differentiy: 
Each process instantiates a copy of the data section, 
making globals per-process rather than per-computer 
or per-part. Also, because there is normally one process 
per OpenDoc document, a separate data section usually 
exists for each document that contains a part bound to 
your cditcir. Therefore, you should control the size of 
yt]ur data section so that copies of it don’t take up too 
much memory when multiple documents are open. 

Here’s what you can do to keep the size of your data 
section dowm: 

• Limit your use of global variables — Since globals 
are stored in the data section, use them only for 
those things that must be per-process globals. 

• Use read-only string constants String constants 
that are writeable must be located in your data 
section because the compiler assumes that you might 
write into the memory associated with them. If you 
have the compiler make your string constants read¬ 
only (by checking the iVIake Strings ReadOnly box 
in the PPC Processor panel in CodeWarrior, for 


example), these strings can be put into the code 
section instead of the data section. But remember 
that after doing this, you should not write to these 
string constants. You can still allocate memory in the 
OpenDoc heap for strings and write to them. You 
can also put string buffers, such as Str255 strings, on 
the stack in your code and write to them there. Note 
that any user-visible string constants should be stored 
in resources so that your editor can be localized. 

• Avoid virtual functions — Space is made for virtual 
functions of C++ classes in the data section because 
the virtual tables must be written once (for each 
process) to point to the functions residing in the 
read-only code section. You can make the virtual 
table smaller by not making functions v^irtuaL It’s 
best to design your classes with as few virtual 
functions as possible, adding more only as the need 
arises. 

• Reduce the number of transition vectors — For each 
import and export syTnbol in a library, there’s a 
TA^ector, or transition vector. (CFM-68K calls dtem 
XVectors.) The TVector must be writeable because, 
like a virtual table, it has to be wTitten once to point 
to the corresponding memory address when the 
code is loaded. 

Reduce exports. By minimizing the number of symbols 
that are exported, you can save memory. Symbol name 
strings are stored in the PEF (Preferred Executable 
Format) container of your code fragment. If you’re 
using a shared librar}^ that contains a framework or set 
oi C++ classes, you usually need to export the symbols 
for each of the member functions in the shared Ubrary 
and import the relevant ones into your part editor to 
call them or subclass them. C++ functions have long 
symbol names because they include type signature 
information. As a result, the size of your code fragment 
can increase significantly. 

This is particularly noticeable if you have multiple 
part editors that reference the same code, since they’ll 
all have large tables of symbol names. You can use a 
tool like DumpPEF to check what type of information 
your code fragment contains and how much space it’s 
taking up. 

A workaround is to statically link classes to your part 
editor. This means fewer imports and less memory 
used. Of course, it you do this, you lose some of the 
advantages of sharing code via a shared library^. 

Package multiple part editors intelligently. If 

you’re writing a suite of part editors for end users, it’s 
a good idea to package them as separate editor files in 
the Editors folder. However, as mentioned earlier. 
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if you want to share common code, the amount of 
memory that’s used by all the editors combined can be 
substantial. 

Packaging all your part editors and the common code 
in a single code fragment reduces the number of imports 
and exports to almost nothing. But then you can't update 
just one of the editors in your suite ~ you have to 
replace the entire shared library, IPs also detrimental if 
only one or two of your editors are being used, because 
the system loads the entire code fragment but only a 
portion of it is being referenced. This isn’t as much of a 
problem if the user has virtual memory enabled, but 
without it, memory is wasted. 

To combine multiple OpienDoc part editors into one 
code fragment, you have to compile the code for all of 
them together. You can do this either hy putting them 
all into one project or by having multiple projects 
generate static libraiy^ files and a master project that 
includes each of the single-part libraries. Then you 
need to make sure that the Class Data s>Tiibols for all 
the parts are exported as separate symbols, by using 
pragmas or a “.exp” file. Finally, you must include the 
hi map’ resources from all the individual editors in the 
combined file. Of course, the IDs of these resources 
can’t cHinfiict, but since Open Doc tloesn’t require any 
specifi c resource IDs for *nniap^ resources, tliat should n ’t 
be a pn>blem to set u[). 

Use SOM classes instead of C4--f’. If you’d like to 
separate framework cotie from part editor code (for 
example, to have multiple etlitors share the same 
framcM^ork or set ol classes), note that there are several 
advantages to using SOM classes insteatl of C++ classes. 

Willi SOM on the Mac OS, you only have to export 
the class’s ClassData symbol, 'f he virtual tables are 
maintained hy the SOM kernel- they tlon’t exist in your 
data section. 

Since SOM has so little overhead, you can package 
multiple editors as separate code fragments (either in 
separate, replaceable files or in a single file). Editors 
that aren’t being used won’t be loaded. 

You can also reduce tlie granularity of your shared 
libraries, such that different classes are in different 
shared libraries {again, in separate files or the same 
file). This allows you to split up your framework so that 
only the sections that the client needs are loaded into 
memory. For example, if you have one part editor that 
embeds other editors and another that doesn’t, but they 
share the same framework, the framework’s embedding 
code can be in a separate shared Ubrary from the code 
that’s needed by all part editors. 


SOM supports release-to-release binary compatibility, 
and it deals with the fragile base class problem of C++, 
It also defines a binary interface that supports languages 
other than C++. Currently, emitters on the Mac OS for 
C and C++ are available. Other languages can also be 
supported. 

Don’t be afraid to use SOM. Better tools for building 
SOM classes are being released. In particular, Direct- 
to-SOM support has been added to Metrowerks 
CodeWarrior’s C++ compiler and Apple’s MrCpp, so 
you can build SOM classes with much less effort and 
witii a more familiar syntax. 

Use #pragnia internaL Space is also wasted wlien it’s 
set aside for instructions and never used. By default, 
functions on a PowerPC^'^ processor are assumed to be 
external, so for the processor to jump to the routine, it’s 
expected to go through a TVector, To do this, the 
compiler leaves room in the code for the linker to add 
the necessar)^ instruction to restore the TOC (Table Of 
Contents) after a jump to a TVector, If it turns out that 
the routine is in the same code fragment, restoring the 
I OC isn’t necessary, hut because the space has already 
been inserted, the linker has little recourse but to put a 
no-op instruction in that place. (The code was generated 
expecting certain offsets, so the linker can’t shuffle the 
code around easily) Space is then wasted for calls that 
are internal to the code fragment. 

There are a couple of wayj> around this. One thing 
you can do is to declare a function with the keyword 
static (this means that it can’t be used outside the file 
it’s defined in) so that the compiler can tell it’s an 
internal function. You can also use the internal pragma 
in CodeWarrior. The following cckIc marks the 
declaration of tw^o functions as internal by enclosing 
them in a #pragma internal block. This informs die 
compiler that calls to those functions can be assumed to 
be internal calls, and it won’t leave space for restoring 
the TOC after a TVector call. 

#pragma internal on 

void InternalFunction(); 

ODfloolean AnotherInternalFunction(short count); 
tpragma internal reset 

Note that a function internal to your code can still be 
an export from your shared library. In this case, your 
header should conditionalize its inclusion of #pragma 
internal for your own use so that external clients don’t 
mistakenly see it as internal. 

This technique is not used for CFM''68K code becouse 

colh ihere are assumed lo be internal unless theyhe marked 

otherwise (wEih #pragiiia import).* 
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The MrPhis profiling too! can also be used to get rid 
of unneeded no-op instriicdons. You can get this tool 
and its documentation on the E.TO, and MPW Pro 
CDs, 

EVERY BYTE COUNTS 

OpenDoc presents a new model tor constructing 
softw^are. However, many of the techniques youVe used 
for the traditional application model can still lie applied 
to the OpenDoc environment. By alsfi incorporating 
some of the suggestions we Ve brought up here, you’ll 
he able to further reduce your part editor’s footprint 
and avoid memory leaks. 


RELATED READING 

This documentation is available on the OpenDoc 
Developer Release CD and on the OpenDoc Web 
site [http://www.opendoc.applexom). 

• OpeoDoc Programmer's Guide for the Mac OS 
by Apple Computer, Inc. (Addison-Wesley, 1995), 
The OpenDoc Class Reference for the Mac OS is 
provided on a CD that accompanies this book. 

• OpenDoc Cookbook for the Mac OS by Apple 
Computer, Inc. (Addison-Wesley, 1995). 


Thanks to Jens Affke, David Bice, and Steve Smith for reviewing 
this column * 
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Gearing Up for Asia With the Text Services 
Manager and TSMTE 


Are you eyeing Asian markets for your application? If so, the smartest 
thing you can do to gear up is to enlist the aid of the Text Setuices 
Manager (TSM), inti'oduced with System 7.1 to help applications 
communicate with utilities that provide text services. Making your 
application TSM-aware, an easy matter if you're using TextEdit and 
TSMTE, will enable it to use the services of utilities designed to handle 
text input in Chinese, Japanese, and Korean. Your application will also 
be poised to take advantage of the wide variety of text services that 
eventually will be .supported by the Text Seiuices Manager. 



TAGUE GRIFFITH 


Localizing your application for Asian markets, or for Asian language-speaking 
customers in tlie United States, may seem like a tlaunting task to you, but take heart: 
the Text Semces Manager (TSM) makes one aspect of localization, handling keyboard 
input, easier than you might imagine. Part of the WorldScript technology in the 
Macintosh ‘loolbox, the Text Services Manager enables applications and text service 
utilities to communicate without knowing anything ahout each other's internal 
structures or identities, WTen you make your application TSM-aware, yon make it 
possible for your Asian language-speakiiig customers to use your application in 
concert with a utility program that does the necessary conversion of keyboard input. 

This article shows you how to modify your Text Edit-based application to make it 
TSM-aware — that is, so that it makes the app rap Hare calls to the Text Services 
Manager, It doesn't take a lot of modifications, as youll see from the sample 
application (called InlineInputSample) that accompanies diis article on this issue's 
CD and develops Web site. Our applicadon uses 'TSMTE, an extension diat's shipped 
with the system), which extends TextEdit to handle the details of TSM awarenes.s 
with imnimal effort on the part of application WTiters. Using 'TSMTE should he 
sufficient for most applications; however, for intensive text-processing applications or 
applications using a different text-editing engine, you may need to handle all TSM 
processing yourself. 


Before we look at the changes you need to make to your application to make it 
TSM-aw^are, Til briefly explain how^ keyboard input works for Chinese, Japanese, 
and Korean. If y^ou'd like to read more about common problems of localization, see 
“Writing Localizable Applications” in devdup Issue 14, For details on the lext 
Services Manager, consult Chapter 7 of ImidT Machitosh: Text. 


TAGUI GRIFFtTH (togue@appbxom) has 
appeared on stage with several famous rocl; 
bands and would like to marry a rock star when 
he grows up. In his spare time, Togue works in 


Apple's Text and InternationQl Engineering group. 
If anyone out there knows Courtrrey Lovers e-mail 
oddress, please send It to Tague.* 
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ASIAN LANGUAGES AND KEYBOARD INPUT 

As you can guess, supporting keyboard input for Asian languages isn't the same as 
handling English, because dieyVe written in different scripts. A script is a writing 
system that can be used to represent one or more human languages. 

English and other European languages are written in the Roman script, which is an 
alphabetic script. In alphabetic scripts, the various characters of the script are combined 
in different w'ays to form words. ^Vlphabetic scripts have a small repertoire of characters 
compared to other types of writing systems. It’s a simple matter to represent all the 
characters in an alphabetic script on a keyboard. Because there are fewer than 256 
characters in such scripts, it takes only one byte to uniquely identify each character, 
so tliese scripts are knowm as 1-tyrescripts. 

Asian languages are quite different, being written in scripts that include ideographic 
characters borrowed from ancient China. An ideograph is a symbolic character that 
usually represents a single concept, action, or thing. Figure ! shows some examples of 
Japanese and simplified Chinese ideographs. BccatLse each character represents a 
single concept, there are — by necessity — many, many more characters than in the 
Roman script Most literate Chinese speakers kmow around 5000 ideographs, and a 
literate Japanese [mows around 5000 ideographs. Two bytes are required to uniquely 
identify each character in an ideographic script, and thus these scripts are known as 
2-bytesc?ipts. Chinese, Japanese, and Korean also incorporate alternative script systems 
based on syllabic or phonetic characters (characters chat represenc certain sounds). 



japonese 



Chinese 


7i< 

woter 

H 

sun 

D 

sword 

9i 

friend 

^ ' 

f me 

t 

>usy 


Figure 1. Some Japanese and Chinese ideographs and their English translations 


INPUT METHODS 

How is it possible for users of 2-byte script systems to get by with a standard Macintosh 
keyboard? Obviously, they can’t simply press the key corresponding to the one 
character they want out of 3000 or 5000 characters. Enter the text service urility 
known as an input tnethod or ^fivnt-endprocessor {FEI^. An input method allows users 
to type phonetic or syllabic characters on a standard keyboard and automatically 
converts what diey type into ideographic representations. 

For Chinese speakers, the appropriate input method converts keyboard input from 
Pinyin (Roman) or Zliuyinfuhao (phonetic, also known colloquially as Bopomofo) to 
ideographic Hanzd, For Japanese speakers, the input method converts input from 
phonetic Katakana or 1 liragana into ideographic Kanji, as illustrated by the example 
in Figure 2, The input method for Korean speakers converts phonetic Jamo into 
nonideographic Hangul (complex clusters of Jamo), 

Hiragano Konji 

Figure 2, The same sentence as entered in Hiragana and as converted fo Kanji 

Apple emrendy ships four 2-byte keyboard input methods: Kotoeri (Japanese), Power 
Input Method (Korean), Traditional Chinese (as used in Taiwan), and Simplified 
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Chinese (as used in the People’s Republic of China). The same input methods are 
shipped with the Apple Language Kits, and third-party input methods are also available. 

Regardless of the language, all input methods have a similar user interface. ^Tien more 
than one script is installed on the Mac OS, as is the case for localized systems since all 
systems have the Roman script installed, the Keyboard menu becomes available in the 
menu bar. Each available keyboard layout and input method is listed in the Keyboard 
menu; the icon for the active keybcsard layout or input method appears as the menu’s 
tide in the menu bar. Figure 3 shows a Keyboard menu displaying items for Apple’s 
Simplified Chinese and Kotoeri Qapanese) input methods, as well as keyboard layouts 
from some other script systems. The Simplified Chinese input method is active; it’s 
checked in the menu and its icon appears highhghted m the menu bar. The pencil 
icon in the menu bar is displayed only when an input method is active (in other words, 
not when the user is typing in English or another language that doesn’t require an 
input method); it’s the title for the menu belonging to that input method. Some input 
methods use a different icon, but it appears in the same place as the pencil icon. 





Rbout Keyboards 



ESS'S? 


♦ U.S. 


C Brabic 
C fltabic-QlUERTV 







Keyboard layout 


Simpitfred Chinese 
inpuJ method 

Kotoeri 
input method 


Figure 3. 


Input method icons in the Keyboard menu and the menu bar 


BOTTOMLINI VS, INLINE INPUT 

Wien tile user begins typing, the raw text appears on the screen as entered, either in 
^Jhating input uumiow that’s usually displayed in the lower portion of the screen or in 
the application window where the text is intended to appear. The first styde of text 
entry^ is known as Irnttomline input, while the second is called mline input (see Figure 4). 
Apphcations diat aren’t TSM-aware can make indirect use of the Text Ser\ices 
Manager’s floating window sendee to enable bottoniline input (as explained on page 
7-13 of Inside Macintosh: Text), but users generally prefer inline input, which only 
TSM-aware applications c'an offer. TSM-aware applic-atiuns can also offer bottomline 
input, which users may prefer if the size of the text displayed in the document makes 
reading the characters difficult. 

In the case of inline input, the just-entered text appears in what is knowm as the active 
input area or mime hole. Text in the active input area or the floating input window is 
imderlined in gray or highlighted in some other manner, depending on the application. 
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With either bottoniline or inline input, the raw text is converted from its phonetic or 
syllabic representation to ideographic or complex syllabic characters, and the gray 
underline (if there is one) turns to black or changes in some other manner determined 






















Bottomline input Inline input 


Figure 4, Bottomline vs. inline input 

by the application, when the user gives a signal such as pressing the space bar after 
entering a sequence of characters. There may be more than one possible reading of 
a given character sequence, in which case the input method will display a list of 
candidates in a candidate window^ as shown in Figure 5. When the user selects one of 
the candidate readings, the raw text is converted. 





Figure 5* Selecting a conversion option for inline input in □ candidate window 


The user then confirms the converted text, generally by pressing Return. (In Korean, 
conversion happens continuously and automaticaily, and the text is confirmed when 
the user presses either Return or die space bar.) In the case of bottomline input, the 
confirmed text is flushed from the input window and sent to the application as key- 
down events. For inline input, the confirmed text is copied into the application’s text 
buffer (as shown in Figure 5) and the active input area i.s closed. Vl^en the user 
begins typing again, the underline beneath the confirmed text disappears entirely and 
a new active input area opens. 

Before you start feefing overwhelmed by all this, realize that most of the user interface 
elements IVe just described are handled by the input method or "I SMTE and not 
your application. The input method takes all the keystrokes and processes them; your 
application simply draws the input metliod’s text buffer in the application window. 

All you need to do to get the benefit of this kind of text service is to make a few 
modifications to your application. Once your application is TSM-aware, you can 
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work with any input method regardless of language and thus offer your Asian 
language-'Speaking customers the convenience of inline input 

MAKING YOUR APPLICATION TSM-AWARE 

Making your application TSM-aware is a matter of adding calls to send information 
to input methods by way of the Text Seirices Manager, Most of the popular text¬ 
editing engines for the Mac OS other than TextEdit are already TSiVl-aware, One of 
these, WASTE (the WorldScript-Aware Styled Text Engine, developed by Marco 
Piovanelli), makes all but four of the necessary calls: InitTSAWwareApplication, 
CloseTSMAwareApplication, TSzMEvent, and SerTSMCurson These calls need to 
be made by the application. Optionally, a WASTE-based application can install pre- 
and post-TSM-update callback routines. If you use WASTE for your text-editing 
engine, most of the techniques described in this section apply. The WASTE source 
code is available online at many popular Macintosh ftp sites; I highly recommend 
looking at it for examples of how to handle the TSM protocol directly. 

Using TSMTE, as our application InlineInputSampIe does, you can make your 
TextEdit-based application TSM-aw^are with a few mndifications to your event¬ 
handling, cursor-handling, window, and menu code. Most of the changes are quite 
simple and limited to particular subroutines of the application, as demonstrated by 
InlineInputSampIe. Our application is a versif>n of TESample^ a program written by 
Apple’s Developer Technical Support group and provided with many development 
environments as part of the example code (it’s also on this issue’s OD). The code that 
makes our version of the program TSM-aware is conditionalized with qlnline 
cotulitianals so that you can easily pick it out. You might want to rake a look at that 
code as you read this section. 

To s«e the full capabilities of the InllnelnpufSompte application, you need a 

Macintosh with System 7.1 or later localized for Chinese, Japanese, or Korean, or 

with one or more of the Asion language kits installed 


TESTING FOR THE TEXT SERVICES MANAGER AND TSMTE 

Before using the Text Services Manager and TSMTE, we need to check and see if 
they’re available. The Text Sendees Manager is available on all versions of the system 
after 7,1. However, TSiMTE ships only wdth localized version.s of the system and with 
the Apple Language Kits for Uhinese, Japanese, and Korean. The support for inline 
input discussed in this article will he active only while you’re using one of these 
l;mguage,s. Listing I shows tlie code w'e use to check for availability of the Text 
Sendees Manager and TSMl'E. If we were writing our qwti protocol handlers, we 
would eliminate the gestaltTSMl^EAttr test. 

'Lhe selector gestaltTSAlgrVersion returns the version number of the Text Services 
Manager if it’s installed. You should test to make sure that the version is greater than 
or equal to 1, the current version of the Text Services .Manager. This will allow your 
applit'ation to work with future "LSM versions as w'ell. 

INITIALIZING THE APPLICATION 

Once weVe established that the Text Services Manager and TSMTE are available, we 
need to extend our Toolbox initialization sequence to initialize the Text Services 
Manager. This is done by calling In itTSMAwa re Application, We also w^ant to store 
the current state of the Script Manager’s smFontForce variable (the font force flag) 
and set it to false while our application is running. This flag ensures the correct text- 
handling behavior in applications that don’t use the Script iManager. Since we’re 
using the Script Alanager to support text in different languages, we should turn this 
off, as shown in Listing 2, 
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Listing 1 . Testing for TSM and TSMTE availability 

static void CheckForTextServices(void) 

{ 

long gestaltResponse? 

gHasTextServices = false; // unless proven otherwise 

gHasTSMTE = false; // unless proven otherwise 

if (TrapAvailable{_Gestalt)) { 

if ((Gestalt(gestaltTSMgrVersion, SgestaltResponse) == noErr) && 
(gestaltResponse >= 1)) { 
gHasTextServices = true; 

if (Gestalt(gestaltTSMTEAttr, ^gestaltResponse) = noErr) 
gHasTSMTE = BTst(gestaltResponse, gestaltTSMTEPresent); 

} 

} 

> 


Listing 2* initializing as a TSM^iv^are applicoMon 

if (I (gHasTSMTE &S InitTSMi^wareApplication() == noErr)) { 

// If this happens, just move on without text services. 
gHasTextServices = false; 
gHasTSMTE = false; 

} 

// Get global font force flag; make sure it's off whenever we run. 
//Do this even if text services don't exist* 
gSavedFontForce = GetScriptHanagerVariable{smFontForce); 

(void) SetScriptManagerVariable[smFontForce , 0); 


Of course, since we do this work at initialization, we need to clean up when our 
application quits. In our termination routine, we restore the value of the font force 
flag and call CloseTSAlAwareApplication. The font force flag also needs to be restored 
anytime control passes from the application to the system when weVe dealing with 
fonts and such; it particularly should be restored in die case (if a suspend event. 

EXTENDrNG THE DOCUMENT STRUCTURE 

Now we need to extend our document record to store the additional data structures 
related to TSAI awareness. Our application*s original DocumentRecord data 
structure is extended to include two additional fields, as follows: 

typedef struct { 

WindowRecord doeWindow; 

TEHandle docTE; 

ControlHandle docVScroll; 

ControlHandle docHScroll; 

TEClickLoopUPP docClick; 

Boolean modified; 

TSMTERecHandle docTSMTERecHandle; 

TSMDocumentID docTSMDoc; 

} DocumentRecord, *DocumentPeek; 


// added 
// added 
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The TSMTERecHandle is used by TSAITE to maintain the data it uses. The 
TSMDocumentID identifies a TSM document, which is an opaque data stnictiire used 
by the Text Services Manager to maintain the current status of the input methods in 
use. Generally, one TSM document {defined by the TSxMDocument data type) is 
allocated per application window, but some applications may allocate a single global 
TSM document. Since the TSAI document maintains context/state information about 
the current input method, you should customize aliocation of the TSM document for 
your application/s text-handling behavior. 

Each TSM document also maintains a reference constant, which can be set by the 
application. Applications using TSMTE must stuff the TSMTERecHandle into the 
refCon; if yoii^re creating your own handlers, the refCon can be customized to suit 
the needs of your application. 

CREATING AND DELETING A TSM DOCUMENT 

WTien creating a user document, we need to set up die TSM document and the 
T'SMTERecHandle correcdy as illustrated in Listing 3. We pass tour parameters to 
NewTSMDocument. The first parameter indicates the version of the TSM protocol 
that weVe using; currendy, the only defined protocol version is L The next parameter, 
supportedlnterfaces, is an array of OSTypcs that the Text Services Manager uses to find 
components that support the seiwice the client is interested in. For our application, 
we set supportedlnterfaces[0] to kTS 4 MTEliiterfaceType, indicating that we’re using 
TSMTE support. Other applications providing Full TSM support wall want to set 
supportedlnterfaces[0] to LlextService. Currently these are the only defined interface 
types. The final two parameters are a pointer to the TSMDocumentID storage and a 
pointer to our TSM refCon (in this case the TSMTERecHandle). 

(3nce w^eVe allocated the TSxM document, we need to set up the TSM^PERecHandle. 
We set the TextEdit record (or the handle and install UniversalProePtrs for the pre- 
and post-update hmdlers. These handlers are called before and after d'SMTE 
handles the update event. The pre-update handler in our sample appHcadon works 
around a bug in TSMTE version 1.0, and the post-update handler adjusts the scroll 
bar to bring the new text into view. Wc also set the updateFlag and the refCon. 

Obviously, since we allocate certain structures when we create our "fSM document, we 
need to deallocate those stimcturcs before we destroy the TSM document (that is, when 
close the w'indow). Listing 4 shows how to handle deleting a TSjM document 


Listing 3- Creating a TSM document 

if (good && gHasTSMTE) { 

supportedlnterfaces[0] = kTSMTEInterfaceType ? 
if (NewTSMDocumentt1, supportedlnterfaces, &doc->docTSMDoc, 
(long) fiidoc->docTSHTERecHandle) == noErr) { 
TSMTERecPtr tsmteRecPtr = *{doc->docTSHTEEecHandle J ? 
tstnteRecPtr->textH = doc->docTE; 
tsmteRecPtr*>preUpdateProc = gTSMTEPreUpdateUPP; 
t smteReePtr->po s tUpd at ePr oc = gTSMTEP□s t UpdateUP P; 
tsmteRecPtr->updateFlag = kTSMTEAutoScroll; 
tsmteRecPtr->refCon = (long) window; 

} 

else 

good = false; 
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Listing 4. DeleHng a TSM documenf 

if ( theDocument->doc:TEMDoc I- nil) { 

(void) FixTSMDocmnent (theDocuitient->docTSMDoc ); 
if DeleteTEMDocument might cause a crash if we don't deactivate 
if firstf so... 

(void) DeactivateTSMDocmnent (theDociimeiit->docTSHDoc); 

(void) DeleteTSMDocument{theDocument->docTSMDoc ); 

> 


The FixTSxMDocument call causes the Text Services Manager tcj canfirm the text in the 
active input area and enter it into the user document. In 3 real apjplication you^d tlien 
give the user the opportunity to save the user document before deleting the TSM 
document and closing the window, but we skip that step here. After “fixing” the 
document, we call DeactivateTSxMDocument and then DeleteTSMDocument. We 
need to deactivate the document before deleting it because in certain circumstances 
DeleteTSMDocument may crash if we call it on an active document. 

MODIFYING THE EVENT LOOP 

Making your application TSM-aware with TSMTE requires very little modification to 
your existing event loop code. First we need to give the Text Services Manager an 
opportunity to handle events that might actually be for an input method and not our 
application. This is accomplished by calling TSMEvent and passing in the EventRecord 
returned from either WaitNextEvent or GetNextEvent In our sample application, 
we wrap the call to TSMEvent in the IntlTSMEvent subroutine, as shown in Listing 5, 
to work around a bug that could cause tlie port to be set to the wrong window. 

Listing 6 shows how we modified the application's event loop to call TSiVlEvent 
before handling an event. 


Listing 5, The IntlTSMEvent subroutine 

static Boolean IntlTSMEvent(EventRecord *event) 

{ 

short oldFont ; 

ScriptCode keyboardScript; 

if Make sure we have a port and it's not the Window Manager port, 
if (gd.thePort 1= nil && FrontWindow() i- nil) { 
oldFont - qd.thePort->txFont; 

keyboardScript = GetScriptManagerVariable( siriKeyScript) ; 
if (FontToScript[oldFont) 1= keyboardScript) 

TextFont(GetEcriptVariable{keyboardScript, smScriptAppFond}); 

> 

return TSMEvent(event); 


Next, input methods must be given a chance to handle mouse events for the pencil 
menu. MTienever the user presses the mouse button in the menu bar, we need to pass 
the menu selection to the Text Services jManager and see if it*s a system menu before 
we try to handle it as an application menu. We modify the subroutine for handling 
mouse “down events as shown in Listing 7. 
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listing 6. The applicotion/s event loop 


void EventLoop(void) 

{ 

RgnHandle cursorRgn; 

Boolean gotEvent, handledByTSM; 

EventRecord event; 

Point mouse; 


cursorRgn = NewRgn(); 
while (IgQuitting) { 

// Set global font force flag so other apps don't get confused* 
(void) SetScriptManagerVariable { smFontForce, gSavedFontForce}; 


if (gHas^^aitl^extEvent) { 

GetGlobalMouse(&mouse); 

AdjustCursor(mouse, cursorRgn); 

gotEvent = WaitNextEvent(everyEvent^ seventy GetSleep(), 
cursorRgn); 


} 

else { 

SysteinTask(); 

gotEvent = GetNextEvent(everyEvent ^ tevent); 


> 


// Clear font force flag again so it doesn't upset our operations- 
gSavedFontForce = GetScriptManagerVariable(smFontForce); 

(void) SetScriptManagerVariable(smFontForce, 0); 


if (gHasTextServices) { 

handledByTSM = IntlTSM£vent(&event); 
if (JhandledByTSM && gotEvent) { 

Ad j u s tCu r s or(even t * whe re, curs orRgn); 
DoEvent{&event); 

} 

else 

DoIdle(); 

} 

else { 

if (gotEvent) { 

AdjustCursor(event-where, cursorRgn); 
DoEvent(tevent); 

} 

else 

DoIdleO? 

} 

) 

} 


iVfter calling our subroutine to adjust the menus so that the invalid items are dirrimed, 
we pass the menu selection to the Text Services Manager. We call TSMMenuSelect 
with the menu result as a parameter. If the selection is in the pencil menu, the Text 
Services Manager will handle it for your application and return true; otherwise, it will 
return false and your application should handle the selection normally. Regardless of 
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Listing 7* Checking the menu selection in the mouse-down event handling 

case xnMenuBar; // Process a mouse-down in menu bar (if any). 

MjustHenus(); 

menuResult = MenuSelect{event->wherej; 

if (i[gHasTextServices && TSMMenuSelect(menuResult))) 

DoHenuCoiimiand( menuResult); 

HiliteMeTiu{ 0); // Weeded even if TSM or Script Manager handles 

// the menu. 

break; 


the results of TSMMenuSelect, your applicatitju needs to call HiliteMenu(O) to finish 
handling the selection. 

The next step in handling a menu seiection is to confirm the text in the active input 
area with a call to FixTSMDocument before performing the menu action. This is 
recommended in the current Macintosh Human Interface Guidelines. But this guideline 
is somewhat contested, so if you don’t think it makes sense for your application, you 
might consider a more selective polic}^ for automatically confirming inline input. 
Whatever you decide, remember to be consistent and try it out on real users. 

Now that weVe finished modifying our menu-handling code, well move on to 
modifying our window event handler, as shown in Listing 8. We need to make sure 
that the active TSM document is changed when necessary Assuming that we’re 
allocating one TSM document per user document or window, we also need to handle 
window activate and deactivate events differently When we receive a deactivate 
event, we need to call Deactivatel'SMDocument on the "I'SM document associated 
with that window. Similarly we need to call xActivateTSMDocument when we receive 
an activate event for our window. 


Listing 8. Handling v^indow events 

void DoActivate(WindowPtr window, Boolean becomingActive) 

{ 

RgnHandle tenipRgn, cXipRgn; 

Rect growRect; 

Doc ume nt Pee k doc; 

if [ I sDocuinentffindow{ window)) { 
doc = (DocumentPeek) window; 
if (becomingActive) { 

... // TextEdit-handling code 

if (doc->doc'rSMDoc J= nil) 

(void} ActivateTSMDocunient (doC”>docTSHDoc); 

} 

else { 

if (doc->docTSMDOG 1= nil) 

(void) DeactivateTSMDocument(doc->docTSMDoc); 
... // TextEdit-handling code 

> 

1 
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If you use your own scheme for allocating TSM documents, be sure to call 
ActivateTSMDocument and DeacdvateTSMDocument when appropriate. If you 
don’t activate TSM documents correctly, the system can get conftised and revert to 
Roman, in which case the user may click on a run of 2-byte text and not get inline 
input. If you^re debugging your progt^arn and this happens, check to see what the 
current keyboard script is by calling 

keyScript = GetScriptMgrVariable(keyScript); 

If the keyboard script is smRoman, the problem could be related to activating and 
deactivating TSxM documents. 

We finish up our event Iot>p modifications by ensuring that our application handles 
mouse-moved events in a way that w^orks with the Text Services Manager and input 
methods. Input methods need to track mouse-moved events within the content area 
of yrmr application, because when tlae user moves the cursor over an active input area, 
the input mediod needs to change the cursor’s shape. This is demonstrated in the first 
half of Listing 9, Before attempting to change the cursor’s appearance, your application 
should call SetTSMCursor, which returns a Boolean indicating whether the input 
method has already changed the cursor’s appearance. 


Listing 9. Allowing the input method to change the cursor 

// Before ve commit to anything, let's check whether some text service 
// has a different idea. 

if ( ! (gHasTextServices && SetTSMCursor(inouse) )) { 

// Change the cursor and the region parameter, 
if (PtInRgn(mouse, iBeamRgn)) { 

SetCursor (i^^GetCursor {iBeamCursor )); 

CopyRgn(iBeamRgn, region)? 

> 

else { 

SetCursor{&qd.arrow); 

CopyRgn(arrowRgn, region]; 

} 

} 

//No matter how nice the region, with text services it can't be bigger 
// than a point. Yes, this defeats the purpose of all the calculations, 
if (gHasTextServices) 

SetRectRgn{region, mouse.h, mouse.v, mouse.h, mouse.v); 


Now we need to setup the correct mouseRgn parameter to WaitNextEvent. To work 
correctly with input methods, our application should create a mouseRgn that’s no 
larger than a point, as shown in the second half of Listing 9. If we don’t set up this 
region correctly, the input method may not be able to interact with our users as they 
would expect. Yes, being forced to use a point-sized region sort of defeats the purpose 
of a mouseRgn. WeVe working on extending the Text Services Manager so that you 
can obtain the region that the input method is interested in, but for now you’ll just 
have to live with this limitation. 

ADDING FONT-KEYBOARD SYNCHRONIZATION 

Both TextEdit and WASTE automatically perform font-keyboard symchroniziition, 
meaning that they adjust the Keyboard menu so that the current keyboard layout or 


42 


d^vehp Issue 29 March 1997 






input method reflects the user’s font selection. For instance, if the user selects 
Chicago or Courier (Roman fonts) from the Font menu, the application sets the 
current keyboard to a Roman keyboard layout (U.S,, German, Italian, or whatever 
the default Roman keyboard is, according to the localizer). Similarly, if the user 
selects Osaka or HonAlincho (Japanese fonts), the keyboard h synchronized with the 
font selection. 

If you’re not using TextEdit or WASTE, you can add the code in Listing 10 to 
provide font-keyboard synchronization. Using Toolbox routines, we determine the 
script of the font from the font ID. Then we call KeyScript, which changes die 
Keyl)oard menu settings to the default keyboard and input method combination for 
the new script. 


Listing 10. Synchronizing the keyboard with the font selection 
case mFonti 

GetMenuItemText(GetMenuHandle{mFont), menultem, theFontMame); 
GetFNuin(theFontKaiie, ^theFontlD); 
theTextStyle.tsFont = theFontlD; 

TESetStyle{doFont, fiitbeTextStyle, true, te); 
if ((*te)*>selEnd - (*te)->selStart > 0) 
theDocimeiit->modif ied = true? 

AdjustScrollbars(window, false); 
theScript = FontToScript(theFontlD); 

KeyScript(theScript); 
break; 


Font-keyboard synchronization is another one of those contested international human 
interface issues. Japanese users tend to be very divided on tlie issue, since this feamre 
makes it difficult to set Roman characters to the Osaka font (the workaround is to select 
the Roman mode within the input method after selecting the Osaka font); however, 
users working in most other 2-byte languages like font-keyboard synchronization. 
Again, the best idea is to try out this interface feature on sevend real users and get 
their impressions. 

OTHER USER INTERFACE ISSUES 

When you make your application TSM-aware, you may need to work around a couple 
of other user interface issues. One of them is implementing passwords. When the 
user is typing a password, you don’t w^ant an input method to come up, so you should 
change the current keyboard layout to the Roman default. This is accomplished 
similarly to font-keyboard synchronization, using the following code* 

KeyScript (smRomati); // Switch to Roman, 

KeyScript(smKeyDisableKybdSwitch); // Lock out keyboard switching. 

//Do your password stuff here. 

KeyScript{smKeyEnableKeyboards); 

KeyScript{smKeySwapScript); 

If you’re writing game software, in play mode the user can’t or shouldn’t be 
manipulating input with an input method. In this case, you should also change the 
current keyboard layout to Roman, and you might want to lock out keyboard 
switching. In certain other inodes (such as the high score list), users do need the 
sendees of an input method, so you should restore the original keyboard layout. 
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Also, even though mc}st users prefer inlme input, some actually don’t like it, or they 
prefer the bottoniline style of input in certain situations. For example, it’s difficult to 
distinguish Kanji characters at point sizes smaller than 12, so when the user is working 
on a document in a small font, looking at the raw input in a larger font in die floating 
input window may be desirable. You sliould provide a preference mechanisni so that 
the user can select either inline or bottomline input. This is implemented by calling 
the TSM function UseTnputWindow and then passing it the document ID and a 
Boolean indicating whether the user wants inline input, 

TESTING YOUR APPUCATiON 

Once youVe made your application TSxM-aware, you'll want to test it vith a variety 
of input methods, since not all of them interpret the TSM protocol in quite the same 
way. If you’re fortunate enough to have testers w^ho speak Chinese, Japanese, or 
Korean, youVe g{>t it made* But if you don’t have anyone around who speaks these 
languages, it’s still possible to test your application in English witli an input method* 
For some suggestions on how non-Asian language speakers can successfully test your 
code, see “Testing Two-Byte Script Support.” 

THE TSM PROTOCOL 

Although TSMTE should provide enougli support for most application developers 
who want to make tlieir Texth'dit-based applications TSM-aware, some developers 
may want or need to handle all the details themselves. 'This section provides a very 
brief overview of the TSM 1.0 protocol for the benefit of the latter. 

The 'FSM protocol is based on the exchange of Apple events between the application 
and the input method, allowing them to share information about the active input 
area. The protocol consists of a suite of three required events (Position To Offset, 
Offset To Position, and Update Active Input Area) and an optitinal fourth event (Get 
Text)* 

THE POSITION TO OFFSET EVENT 

The Position To Offset event is used to convert a global pcisition into a meaningfui 
offset in the document’s text buffer. This event is sent from the input method to die 
application when the input method handles an event that occurs within the context of 
the application content. (Remember that you need to call 'I'SMF.vent to give the Text 
Sendees Manager a chance to handle mouse and keyboard events*) 

The application must respond to this event by extracting a point on the screen from 
the Apple event and convening that point to an offset in the text of the particular 
document. In the TSM protocol, offsets are defined as long integers* The application 
returns the offset as a key in die reply event* 

THE OFFSET TO POSITION EVENT 

The Offset Ti Position event is sent by the input method when it needs to determine 
the global position of a particular document offset. When responding to this event, 
the application must return a global point corresponding to this offset. Optionally, 
the application can also return information about the tyjiographical style and 
orientation (vertical vs. horizontal) of the text* Each of diese elements is returned as 
a key in the reply event* 

THE UPDATE ACTIVE INPUT AREA EVENT 

The Update Active Input Area event is used by the input method to ask the 
application to update the active input area. The event contains an offset range array 
that breaks the updated text into particular range.s. The offset range is accompanied 
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TESTING TWO-BYTE SCRIPT SUPPORT 

BY GREG ANDERSON 

I know wha! youVe thinking: ^'Great, now I can odd 
support for 2-byte scripts to my application* But I can't 
read Japanese or Chinese characters^ so how am I 
supposed to test my code to make sure It does the right 
thing with 2-byte characters?" 

Good news: You don't have to learn Japanese or Chinese. 
Instead, you can test your code using the 2-byte Roman 
input mode provided by Kotoeri. That's right — ) said 
"2-byte Romon." 

Most of the characters m the ASCII character set ore 
replicated in one section of the Japanese 2-byte character 
set; you'll find the numbers and letters oround $8250 to 
$829A. The 2'byte Roman choracters look like their 1-byte 
counterparts, except that they're alwoys monospaced and 
they take about twice as much space horizontally as the 
1 -byte charocters do. These charocters ore very useful for 
testing 2-byte script support, because they look the same 
as the characters you use every day but they behave like 
other 2-byte characters such as Chinese and Japanese 
ideographs. 

Entering the 2-byte Roman characters is easy. After you've 
installed the Japanese Language Kit, choose Kotoeri from 
the Keyboard menu (shown earlier in Figure 3) and dick 
the button labeled with the wide uppercase A in the 
operations palette, which will then look like this: 


--——^— m 

z 

sap 

Z|A 


[l|l£ 



Then just type Roman characters the same way you 
normally would. For example, if you want a Q, hold down 
the Shift key and press the Q key on the keyboard. You're 
now reody to edit 2-byte Roman choracters in your 
application to moke sure it handles them correctly. Here 
ore some things to check: 

• Is the insertion point drawn in the right place, or are 
you using □ Romon font to measure Japanese text? 

• If the insertion point is postHoned after a 2-byte 
character and you press the Delete key, is the entire 
chorocter deleted, or do you leave the first byte 
dangling tn your document? 

• If you add a 2-byte uppercase 8 (which has on encoded 
value of $8261) to your document and use your Find 
command to search for a 1-byte lowercase o (which 
has an encoded value of $61), does your applicotlon 
find the 2-byte B? (It shouldn't, and It won't if you're 
using ChoracterByteType correctly.) 

If these things work for you, you're well on your way to 
supporting 2-byte scripts in your applicotion. 


by a highlight range, which indicates how the application should highlight the 
parricular range of text. 

THE GET TEXT EVENT 

Get Text is an optional event used only by Kotoeri, the Japanese input method, and 
some third-party Japanese input methods. It’s documented in a March 1994 technica! 
note by Takayuki Mizuno, available only in Japanese and roughly entitled “Kotoeri's 
Private Apple Event, Get Text.” It’s an extension to the TSM protocol developed by 
Apple as a way for an input method to retrieve text that has already been confirmed. 
Since most localized Japanese applications support this event, your asers wiW 
probably expect it from your application as well. 

TSMTE provides support for the Get Text event, so if you use the techniques in this 
article your application will be able to take advantage of this extension. The Get Text 
event is defined in Table E Listing 11 demonstrates how to handle the event directly, 

TSM NOW AND FOREVER 

Although the changes required to make your TextEdit-based application TSM-aware 
are small, they dramatically overhaul the experience available to .^sian language- 
speaking users. Try compiling our sample application both with and without the 
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Table 1 . Definition of the Get Text event 


Event class 

Event ID 

Requested action 

kTextServiceCiass 
kGetTexJ (= 'glx^] 

Rehjrns fhe currenf sebcfion 

□s the return parameter 


Required parameters 

Keyword 

key Docu men \R efco n 

Descriptor type 

typeLongInteger 

Data 

Standard refCon parameter 


keyAEServerlnsJanc© 

typeCom pon e nt! nsta nee 

Standard component instance 
parameter 

Optional parameters 

keyAEBufferSize *buff*) 

typeLongInteger 

Moximum number of bytes the input 
method can receive 

Return parameters 

keyAETheData 

typeText 

The text specified by the current 
selection. The moximum byte length 
h specified by the keyAEBufferSize 
parameter. Any portion of the text 
that exceeds the buffer length 


Listing 11 * Handling the Get Text event 

pascal OSErr HandleGetText(const AppleEvent ^theAppleEvent, 

const AppleEvent ^reply^ long handlerRefcon) 

{ 

Ipragma unused (handlerRefcon) 

OSErr err; 

Componentlnstance serverinstance; 

TSMTERecHandle docRefcon; 

Handle text; 

Siae textLen; 

// Identify event and get document refCon and server instance, 
err = IdentifyTSMCallback{theAppleEvent, ^docRefcon, 

&serverInstance); 

if (err) return err; 

// Get selected text from document. 

HLock((Handle) docRefcon); 

err = DoGetText( docRefcon, serverinstance, &text, stextLen); 
HUnlock{(Handle) docRefcon); 
if (err) return err; 

// Add selected text as return parameter. 

HLock(text); 

err = AEPutParamPtr(reply, keyAETheData, typeText, (Ptr) *text, 
textLen); 

DisposeHandle(text); 


return err; 

} 


(continued on next page) 
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Listing 11. Handling the Get Text Apple event fconfrnuedj 

OSErr DoGetText{TSMTERecPtr tsmteRecPtr, ComponentInstance 

server Instance, Handle ^^text. Size *textLeii) 

{ 

#pragma unused (serverInstance) 

TEHandle hTE; 

short selStart, selEnd; 

hTE = tsniteRecPtr->textH ? 
selStart = (*hTE)->sel£tartf 
selEnd = (*hTE)->selEnd; 

*textLen = selEnd - selStart; 

*text ^ NewHandleClear(*textLenI; 

HLock((Handle) *text ); 

BloclcMove( (Ptr) (*( (*hTE)->hText) + selStart), (Ptr) {**text), 
*textLen); 

eunloc k((Hand1e) * text ); 
return noErr; 


inline support flag set so that you can see the difference it mahes to users. Even if you 
don't have plans to ship your application localized for Chinese, Japanese, or Korean, 
making St TSM-aware will please your users who have an Apple Language Kit installed 
and want to use your application with their non-English data. 

Besides having an immediate payoff, the work you do to make your application 
TSM-aware will have a hiture payoff as well, VVTiile version 1.0 of the Text Services 
Manager offers support solely for keyboard input methods, future versions will be 
part of the framework for supporting handwriting and speech/dictadon input 
methods as well as more general text services such as interactive spelUng checkers 
and intelligent document scanners. By making your application TSM-aware now, 
you'll be poised to take advantage of the wide variet)" of services that will be available 
with TSM2.0. 
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• "Writing Localizable Applications" by Joseph Ternasky 
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• Guide fo Macintosh Software Locol/zofion by Apple 
Com pu ter, Inc. (Add i so n-We si ey 1992). 

• Inside Macintosh: Text by Apple Computer, Inc. 

(AddIson-Wesley 1993), Chapter 7, Text Services 
Manager," 


• Technotes TE 27, "Inline Input For TextEdit With 
TSMTE/ and OV 20, "Internationalization Checklist." 

• Understanding Japanese Information Processing by 
Ken Lunde (O'Reilly & Associates, 1993), 

• Writing Systems of the World by Akira Nakanishi 
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Thanks to our technical reviewers David Bice, 
Deborah Grits, Osman Gurocar, John Harvey, 
and Yasuo Kida J 


GEARING UP FOR ASIA WITH THE TEXT SERVICES MANAGER AND TSMTE 


47 









PRINT HINTS 

Sending PostScript 
Files to a 
LaserWriter 


DAVE POLASCHEK 


A question that popped up pretty often for me when I 
worked in Apple’s Developer Technical Support group» 
and that continues to appear in the Mac programming 
newsgroups on the Internet, is “How do I send 
PostScript^^ files to a LaserWriter?” The simplest 
answer appears to be to use the PostScriptHandle 
picture comment. Wrong! In the Print Hints column 
“The Top 10 Printing Crimes Revisited” in devdop 
Issue 26,1 said that this would be a misuse of the 
PostScriptHandle picture comment, but I didn’t give a 
full explanation of just how to send files to a printer 
This column will explain how to send complete 
PostScript files the correct w'ay. 

Ifirst, though, l\\ like to backtrack a little and explain 
more thoroughly why you shouldn’t use the picture 
comment to send complete PostScript files* After all, if 
you do implement code that uses this technique, the 
files get to the printer, pages ctune out, and diings seem 
mostly to work* V\Tiat’s the problem? 

WHY NOT USE POSTSCRIPTHANDLE? 

The problem with using the PostScriptHandle picaire 
comment to send files to a printer is that youVe using 
the Printing Manager to do some of the work for you 
and then bypassing it unexpectedly* The problems that 
will show up when you do this may not be obvious, but 
when a user does notice them it can lead to confusion* 

First, when you use the PostScriptHandle picture 
comment, the LaserWriter driver has already set up 
the PostScript state for QuickDraw imaging. It has 
changed the coordinate system and has sent down the 
md dictionary that it will need to draw pages* At best, 
this is extra baggage that your PostScript files don’t 


neetl in the way At w^orst, since the driver has changed 
the coordinate system, your PostScript file may not 
print correcdy There’s also a chance that the extra 
memory used by the LaserWriter’s PostScript 
dictionary may cause your job not to print at all. 

Second, using PostScriptHandle is wasteful. If 
background printing is enabled, the complete PostScript 
file, plus the extra tilings you don’t need, will be spooled 
to the user’s hard drive. Since what youTe interested in 
is just getting the file to die printer, diis is wasteful. In 
some cases, the job won’t even be able to print, since 
your user won’t have enough free space on the hard 
drive to hold a second copy of the PostScript file. 

Finally, diere’s an acstlietic problem* The Printing 
Manager counts the pages that are going to be sent by 
looking at how many times PrOpenPage is called during 
your print job. If youVe got a rauldple^page PostScript 
file, the pa^ge count displayed by the Printing Manager 
will be out ofw^hack. MTiile messages like “Printing 
Page 4 of 1” won't actually hurt the user, spreading 
confusion is bad, 

THE RIGHT WAY(S) 

There are actually two right ways to send PostScript 
files to the printer. They’re essentially die same in that 
you open a connection directly to the printer and send 
it the file you want to print, but the implementations 
are very different. You can either use classic networking 
and the PAP Wc>rkStatif>n,o librar>', or you can use 
()]>en Transport, which contains support for the PAP 
protocol. (For mf>re on PAP, see “PAP? WTiat’s That?”) 

The classic networking solution has the advantage that 
it’s available in all Macintosh computers, out of the box. 
But it’s more diflficuk to im[)lcmcnt. Since you’re 
working at a lower level, there’s more room for you to 
get things WTong — but there’s also less worry of 
having library code that doesn't tlo things the way you 
wimt. Note that your code (at least part of it) can’t be 
Pow'erPC native, because the libraries arc 680x0 only. 

Open Transport is a much sim[)lcr way to implement 
sending PostScript file.s to your printer. You Talk to the 
networking library at a higher level, and you get a 
PowerPC-native implementation networking. But 
of course you lose compatibility with older Macintosh 
models. 


DAVE POLASCHEK (davep@besf.conn, http://www besrconn/ 
-davep/) now worb for LoserMosler Corp., where he does "Mac 
things" that confuse the people who actually build printers, since 
Dave seems to spend most of his time designing spiffy icons and 
then dragging them around his screen. In his spore time, Dave 


scrapes ice off his windshield, jump-starts cars, and de-ices locks. 
Earlier this year he cut a hole in o lake and spent hours sitting on 
the ice waiting far fish to hnd his hook (while he consumed □ 
judicious amount of ontifreeze). Who said life in Minnesota isn't 
exciting?* 
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PAP? WHAFS THAT? 

The Printer Access Protocol (PAP) is the protocol spoken by 
a[| LaserWriters [and third-party Mocintosh^ompatible 
PostScript printers). It's designed around a few simple Ideas: 

• Only one computer can be talking to the printer at 
once, so there's a unique connection between the two. 

• When the printer is ready to receive some dato, it will 
ask the computer for that data. Similarly, when the 
printer wants to send data back to the computer, the 
computer must hove already osked for that data, tn 
other words, a read must always be active. 


• There's a separate status channel for the printer to 
report things like "Printer On Fire" or "Paper Jam." 

This lost point means that there are actually multiple 
connections open for the one connection to the printer. 
This is a ma|or source of the complexity of the code in the 
classic networking case. Open Transport hides this 
complexity from you. 

You can find out more about PAP in Chapter 10 of inside 
AppleTalk, 


WeTl look at both tliese solutions; sample code for each 
one accompanies this column on this issue’s CD and 
develop'^ Web site. The choice of which technique to 
use is up to you. Note also that there may be others 
more attractive alternatives in the future. For now, 
however, these are the two best options. 

The sample code for the classic networking solution is 
the SendPS tool — an MPW tool ratlier than a full 
application, but still useful for demonstrating how 
things work. The process is also described in the 
MacTutor article “Laser Print DA for PostScript.” If 
you’re interested in the nitty-gritty details, consulting 
the ctide and tin at article is your best bet. Here I’m just 
going to give an overview of the code. In a few cases, 
ni make suggestions for how you might enhance the 
code to make a real-world application. 

The main tlTing you need to understand about the PAP 
library that Apple supplies for classic networking is 
that it reports the connection status to you via a few 
variables rather than by way of completion hmctions. 
It’s nor truly asynchronous code, so if you want to write 
a program that will nin happily in the background, 
sending PostScript files to a printer, youVe got some 
extra work to do. Tt’s possible, but a little tricky. 

TMren we^re in the process of opening a connection (in 
the code near the call to Pi\POpen in sendps.c), we 
look at the wstate variable to tell us what’s happening. 
All these state variables have three basic states: a 
positive value means we’re waiting for the printer; 
negative values are errors; and 0 means the operation 
we’re watching has completed. We also call PAPStatus 
periodically to get the printer’s status so that we can 
display it to the user. 

Once the connection is opened, we issue a PAPRead 
call. This is necessary because when the printer wants 


to talk to us, it can’t just tell us it’s ready to talk, but 
rather we must have asked it for some data first. 
(Remember, PAP is a protocol where the parties have 
to ask for data.) We check the estate variable 
periodically to see if the printer has said anything to us. 
When it does, we need to read the data it has sent us 
and issue another PAPRead call. 

Now we’re ready to start sending blocks of data. We 
issue a PAP Write call, and for each call, we w^atch the 
wstate variable to see when the write is done. Wliile 
we’re waiting for the writes to complete, we need to 
remember to check the printer’s status and display it to 
the user (our write might be “stuck” because the printer 
is out of paper and can’t print a page, for example; the 
user should see this so that she can replenish the 
paper). 

Once we’ve sent all our data, we send the end-ofTTle to 
the printer. We do this by sending a packet with no 
data, but with the e of flag set. If we’ve got another job 
to send, there’s no need to close the connection and 
reopen it; we can just start sending it as soon as the 
printer acknowledges our end-of-file. 

That’s the quick overview of the SendPS too!. If you 
need more guidance, see the source code; I’ve tried to 
cojnment it so that everything will make sense. 

YouVe not allowed to redistribute the PAPWorkStation.o 
library included with the classic networking sompie code without 
first licensing it from Apple. To license the code, contact 
sw.license@appie.coin for more detells. It's really not that 
expensive, and you don't want to write it oil yourself. Trust me. " 

THE OPEN TRANSPORT CODE 

The main code for the Open Transport solution is 
considerably easier to follow than the classic networking 
code, primarily because you don’t have to worry about 
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multiple state variables in order to send. You simply 
create PAF and PAPStatus endpoints (connections), 
and the main loop calls the Snd and Rev functions for 
the PAP endpoint. There’s a callback function that gets 
notified when the state of the endpoint changes and 
then sets a single state variable to match die state of the 
endpoint. Exception handling can be localized to this 
callback, which makes the code easier to read, and the 
status reporting am be handled in one place as well. 

Because we don’t need to continually poll the state 
variables, it’s much easier to fit this code into an 
application, and die appheation will cooperate better 
with other applications. Getting good performance is 
also quite a bit easier with the Open Transport-based 
code than with the classic networking code, since you 


don’t have to worry about waiting in the wTong place, 
polling a state variable. 

WRAPPING UP 

Implementing code to send PostScript files directly to a 
printer is more difficult than using the PostScriptHandle 
picture comment, but it offers a number of benefits to 
your users. The process is more straightforward, no 
extra print dialogs need to be shown, and no extra 
storage is required for spool files. You can provide as 
much or as litde status infonnarion as you like (for 
example, you could add progress bars showing liow^ 
much of the job is completed). And performance 
should improve in most cases, since you’ll be talking 
direedy to the printer, rather than through the layer of 
the Printing Manager. Convinced? I should hope so. 


RECOMMENDED READING 

• inside Macintosh: Open Transport and Open Transport 
Client Developer Note (Apple Computer, Inc., 1 996), 
available on the Open Transport Web site, http:// 
WWW. devworld .Q pplexom/dev/open transport/. 

• Inside Macintosh: Network mg by Apple Computer, 

Inc. (Add I son-Wes ley, 1994) and Inside AppleTalk, 

2nd ed., by Apple Computer, Inc. (Addison-Wesley, 
1990). 

• Macintosh Technical Q&A QD 35, "Determining the 
Selected Printer's Address," 


• "Laser Print DA for PostScript" by Mike Schuster, 
MacTutorVol. 2, No. 2 (February 1986). Articles from 
MacTutor, since renamed Mac Tech Magazine, can 

be found at http://web.xplain.com/mactech.com/ 
magazi ne/feahjres/articlea rchives. html. 

• Lost Beauties of /he English language, by Charles 
Mackay, LL.D. (London: Bibliophile Books, 1987). 
Originally published by Chatto & Windus in 1874. 

• The UNIX-Hoters Handbook by Simson Gorfinkel, Daniel 
Weise, and Steven Strassmon (IDG Books, 1994), 


Thanks to Rich Kubota, Quinn "The Eskimo!", Steve Simon, and 
Tony Wingo for reviewing this column.* 
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High-Performance ACGIs in C 


Asynchronous Common Gateway Interface (ACGI) programs allow 
Macintosh HTTP sejwers to do external processing tasks ranging from 
custom. HTML forms processing to controlling hardware devices. ACGIs 
are usually written in AppleScript (which limits them to handling only 
one server request at a time). High-performance ACGIs, ones that are 
capable of handling multiple simultaneous requests, need to be written 
in a high-level language like C. The resulting ACGI will work with 
any HTTP server that supports the WebSTAR WWWQ. Apple event 
suite. 



KEN URQUHART 


Now that you*ve got your IITTP server up and ninning on yoor xMacintosh, people are 
flocking CO your Web sire by the thousands. The only problem is that youVe written all 
of your Asynchronous Common Gateway Interface programs (AC]GIs) in AppleScript 
and their performance is leaving much to be desired. You know you should be writing 
your ACGIs in C for speed, but you think that will be a lot of work. 

Well, have I got news for you! A ftill-blown, multithreaded, high-pertormance ACGI 
program for use with Macintosh HTTP servers is easier to write than you think. If 
you' ve worked through one of the introductory Macintosh programming books, you 
already know just about everything you need to. 

When all is said and done, an ACGI is little more than a simple, Apple event-aware 
application that knc3ws how to process Apple events in threads. Most of the work is 
concentrated in decoding the Apple event parameters that make up each server 
request. Hopefully you won’t feel so overwhelmed by ACGIs written in C (or any 
other high-level language) after youVe read this article, and you can get on with 
using them to hot-rod your Web site! 


Pve made writing an ACGI easier for you by providing a generic ACGI program, 
wfticb accompanies this article on this issue’s CD and develop^s Web site. I designed 
the program (which PH be referring to as an ACGI ^‘shell”) in such a way that you can 
create your own ACGIs just by customizing a handftd of routines. The messy details 
of accepting multiple requests from an HTTP server, and then handling each request 
in its own tliread of execution, are taken care of for you. The program even relieves 
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you of the burden of LTRL-decoding the post and search arguments {including 
breaking up all of the name-value pairs and translating them from the TSO-8H59 
Latin-1 character encoding used by most browsers into the standard Macintosh 
Roman encoding), 

IVe also provided a rich set of convenience routines that perform the following tasks: 

• give you easy access to all the arguments and parameters that make up a 
server request 

• help you compose your HTML, replies 

• get and set various ACGI performance-tuning parameters 

• allow you to gently turn away new requests wLen your ACGI is very busy 

• gracefully shut down the ACGI if the need arises 

IVe tried to provide enough support to make it possible for you to forget most of the 
details of interacting with an HTTP server and concentrate on writing the code 
needed to implement your custom form processing. 

The ACGI shell program, compiled under CodeWarrior as a PowerPC application 
with no optimizations, takes up a litde under 42K on disk (not including custom code 
that you must add to process your requests), Memor\' requirements are dictated by 
the number of concurrent requests you want to handle and how much stack space you 
allocate to each running thread. In a typical case, the shell should provide uniform 
response to about five to ten concurrent requests in a 1 MB memory footprint, 

WHArS AN ACGI? 

Before I can tell you what an ACGI is, I need to explain what a CGI is. This requires 
a bit of hackground on wLat HTTP servers are all about. 

WHArS A CGJ? 

HTTP servers are designed to do one thing and to do it very well: respond to requests 
from Web brow^sers. If the request is for a file that resides somew^here in the servers 
directory^ tree, the server locates the file, reads its contents, and then sends the 
information back to the browser. Other requests such as image map or form processing 
are handed off to auxiliary programs diat communicate with the sender by using die 
Common Gateway Interface (CGI) protocol, Wien the server receives a request that 
must be handled by a CCtI program, the serv^er starts up ibe CGI (if it wasn’t already 
Rinning) and passes it the request. The CGI is responsible for parsing and decoding 
the request parameters, processing them, and then composing the HTML response. 
The server takes care of returning the response to the requesting browser. 

Being a computer program, a CGI can readily interact widi databases, transaction 
processing systems, or even connected serial devices to process a given request. So 
CGIs allows your Web site to serve up a wide variety of dynamic information. 

The structure of a CGI program is dictated by the HTTP server and by the 
operating system. The first Macintosh HTTP server w^as MacHTTP, wTitten by 
Chuck Shotton. He used Apple events for server/CGI coramunication and defined a 
special event suite (WMTl^Q) for this purpose. He later extended this suite, adding 
several more parameters, when he wrote WebSTAR — the commercial version of 
MacHTTP. His suite has become the de facto standard for server/CGI interaction on 
the Macintosh. As such, you can be sure that most other Macintosh HTTP servers 
will support it. 
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Copies of Chuck ShoHon''s Macintosh HTTP servers, boJh a fully functional 
copy of MacHTTP and a time'limited copy of WabSTAR, are available at 
http: //www, star n i ne .com / soffwo re/so ftwa re. htm I, * 

WebSTAR-like servers use custom Apple events to communicate with CGIs and can 
call them either synchronously or asynchronously 

• Synchrtinous calls require the server to suspend processing while it waits for 
the Apple event reply from the CGI. 

• Asynchronous calls allow the server to send the request to the CGI and then 
continue processing other comiections while the CGI does its work. 

Asynchronous calls are almost alw^ays preferable for a popular Web site that’s 
receiving several connection requests a second. 

SO NOW WMl YOU TELL ME WHAT AN ACGI IS? 

An ACGI is a CGI that’s called asynchronoitsly by the H'lTP server (you’re surprised 
to hear this?). Furthermore, when an ACGI is written to handle each request in a 
separate thread of execution (enabling it to deal with multiple requests simultaneously), 
it’s referred to as a threaded ACGI. 

lo write a threaded ACGI for the Macintosh, you need to understand the following: 

• how Web bro\vsers send CGI requests to HTTP servers 

• how a Macintosh ITITP server uses the Apple event suite to pass 

diese requests along to an ACGI 

• how an ACGI can arrange to process each Apple event in a separate thread 
of execution 

• how to extract the UIlL-encoded data from the Apple events so that the 
ACGI can process it 

While it would he just about impossible to describe each of these points in detail in 
one short article, I do provide brief overviews as I talk about the functions of the 
ACGI shell. 


For more information an writing a threaded ACGI/ refer to the book 
Pianning and Managing Web Sites on the Macintosh: The Complete Guide to 
WebSTAR and MacHTTP^ which covers this topic in detail and h □ good general 
reference. Chapters 10 through 1 5 provide a wealth of information, especially 
Chapter 13, "Writing CGI Applications/ and Chapter 15, "Devebping CGIs in C/* 


Like other threaded ACGI solurions (described in ‘‘Other Teclmiques for Developing 
a Threaded ACGI”), my technique uses cooperative threads as opposed to 
preemprive threads. This allow^s you to call any Toolbox routine you want when 
youVe carrying out your form processing. Preemptive threads currently have many 
'loolbox calling restrictions (see the article “Concurrent Prograeuiiing With the 
Thread Manager” in develop Issue 17). 

THE STRUCTURE OF THE ACGI SHELL 

Just as tiiere are many ways of writing a Macintosh application, there are many ways 
to write an ACGI sheU. IVe taken the simplest possible approach and avoided using 
an application framework like MacApp or PowerPIant. xMy ACGI shell is written in 
plain C and consists of three logically separate code sections: 


HIGH-PERFORMANCi ACGLS IN C 


53 





OTHER TECHNIQUES FOR DEVELOPING A THREADED ACGI 


Processing Apple events in threads has been dealt with by 
several authors, and there are a voriety of solutions 
available. 

The first solution was presented by Steve Sisak in late 
1994 in his Mac Tech Magroz/ne article "Adding Threads 
to Sprocket" His AEThreads library allows you to choose 
which Apple events to process in threads and gives you 
complete control over all thread creation parameters. 

A second, rather different approach can be found in the 
source code for the Mail Tools ACGI written by Jon Norstod 
(available at http://charlotte,acns.nwu.edu/mailtools/ 
techinfo.html). 


Greg Anderson, in his article "Futures: Don't Wait Forever" 
in develop Issue 22, presented a third solution involving a 
predispatch Apple event handler that transparently 
threaded all Apple events. 

John O'Fallon described a fourth method in his MacTech 
article "Writing CGI Applications in C." In 1996, Grant 
Neufeld came up with a fifth solution in conjunction with 
his CGI framework in his MacTech article "Threading 
Apple Events." 

Not wishing to break with this long tradition, the program 
described in this article presents yet a sixth variation on 
the theme. 


• a main program chat receives Apple event requests from an HTTP ser\^er 
and processes them in separate direads of exxecution 

• the set of customizable request-processing routines 

• a set of convenience routines tliat simplify accessing the request data, 
composing HTML response pages, and controlling the runtime behavior of 
the ACGI 

The code is split into two source fdes (aegi.e and wwwx), two include fdes (acgi.h and 
ww^w.h), and one resource file (acgi.rsrc). The main application and the convenience 
routines are located in acgi.c, while the routines that you’ll need to customize are in 
wwwx. I’he include file acgi.h contains the public prototypes for the convenience 
functions you can call from w\\'w.c, while the include file www.h contains the function 
prototypes and data structure definitions used by routines in both source files. 

THE ROUTINES YOU NEED TO CUSTOMIZE 

The fde www.c contains six routines that you’ll need to customize to implement your 
own custom form processing. Four routines are called exactly once by the main 
program while the ACGI is running. A fifth routine is called at idle time in the main 
event loop, while the last one is called to process each HTTP request. 

WWWGETLOGNAME 

When die ACGI starts up, one of the first things the main program does is open a log 
file to write progress messages to. It gets the name of the file by calling this routine: 

c har * WWWGetLogU ame(void); 

Customizing WWWGetLogName allows you to specify the name of the log file. All 
you typically need to do is write something like this: 

char *WWWGetLogName(void) 

{ 

return "acgi.log"? 

} 


54 


iisue 29 Match 1997 






The one gotchti here is that IVe used ANSI file I/O routines to simplify the program 
code. So you must always be sure to return a valid ANSI filename {a plain filename 
fewer than 31 characters long with no full or partial Macintosh file path prepended to 
it). Note that some Macintosh ANSI libraries will allow filenames prefixed by partial 
paths as long as the total length of the string is no longer than 255 characters. 

WWWGETHTMLPAGES 

After the log file is opened^ the main program will ask you to build four HTML error 
pages that are returned to the FITTP server when one of these general errors occurs: 

• The ACGl is declining (refusing) to process requests. 

• The ACGT is too busy to handle a new request 

• The ACGI has run out of memory* 

• The ACGI has run into an unexpected problem. 

The routine you use to construct your pages is as follows: 

void WWWGetHTMLPages(Bandle refused, Handle tooBusy, Handle noHeinory, 

Handlean expec tedError ); 

The main program passes in four handies. Each handle contains a standard HTTP 
response header, and you^re responsible for appending whatever HTML text you 
want for the error pages. This allows you to control the “look and feel” of the error 
messages returned by your ACGI. Perhaps the simplest approach here is to put the 
HTML error pages into text files located in the same directory as your ACGI and 
then append them to the handles with the convenience routine HTMLxAppendFile: 

void WWWGetHTMLPages(Handle refused. Handle tooBusy, Handle noMemory, 

Handle unexpectedError 

HTMLAppendFile(refused, "acgiRefused.html"); 

HTMLAppe ndFi1e(t ooB u sy, "ae giTooBu sy.html"); 

HTMLAppendFile (noMemory, " acgiNoMemory. htial "); 

HTMLAppendFile (unexpectedError, " acgiOnexpected. htral" ); 

> 

Other convenience routines allow you to read the text from string and text resources, 
so you have some flexibility here. The idea behind MA^^^GetHTMLPages is to 
allow you to create your HTML error pages early in the initialization phase so that 
they’ll always he available for use. 

WWWINIT 

After the mam program has completed its initialization steps, you’re given a chance to 
carry out any private initialization you need to do before beginning form processing. 
This might include calling the x\CGI runtime-tuning routines, initializing your own 
global variables, reading resources into memory, building HTAIL template pages, or 
opening connections to external databases and other computers. The prototj^pe is 

OSErr WWWInit(void); 

If you run into problems during your initialization, simply return a nonzero code. 

The main program checks the return code and immediately quits to the Finder wften 
the code is nonzero. 

If you have no special initialization to do, you could write this routine as follows: 
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OSErr WWWInit(void) 

( 

return (noErr); 

} 

WWWQUIT 

Wlien the main program exits \ts main event loop* it calls this next routine to give yon 
one last chance to clean up after yourself (close files, database connections, and so on): 

void WWWQviit(void) j 

If you don't need to do any cleaning up, you can write something as simple as this: 
void WWWQuit{void) { } 

WWWPERIODICTASK 

The main program allows you to carry out idle-time processing by calling the 
following routine at the end of each pass through the main event loop: 

OSErr WWWPeriodicTask(void)j 

This is where you'd place code to check that connections to other computers are still 
alive or carry out any background processing initiated by previous server requests. If 
you have no idle-time processing, you could write die followdiig: 

OSE rr KWWP eriodic Ta s k{void) 

{ 

return (noErr); 

} 

The main program checks the return code ft’om this routine and, if the code is nonzero, 
quits to the Finder (after trying to graceftiliy abort all currently running threads). 

WWWPROCE5S 

'I'he last routine you must customize is the one that processes a server request: 

OSErr WWWProcess{WWWReguest request); 

VA/Tien the IITFP server sends the ACGI a request through an Apple event, the main 
program creates a new thread and passes the Apple event data into die thread. The 
diread extracts the request data from the Apple event and packs it into a private data 
structure, 'Fhe thread then calls WWWProccss, passing a pointer to the private data 
structure in the request parameter. You extract information from the data structure 
with die convenience routines (descrihed later). 

If you need to abort the processing of a request, you can return one of the four error 
codes errWTVW^efQsed, errWWWTooBusy, errWWWTsioMemory, and 
errWTVT\TJnexpected. These cause the corresponding IITMI. error pages that you 
built in the routine WWW^Get! ITMLPages to be rerumed to the server. 

THE MAIN PROGRAM 

As mentioned previously, the main program is a simple Macintosh application — 
simpler than most of the programs described in introductory Macintosh programming 
books. It’s important to remember that an ACGI is meant to interact with HTTP 
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servers, not live users. It doesn’t need any windows, complex menus, or even an 
x\bc>ut box. Its purpose in life is to respond to Apple events and not mouse clicks or 
keystrokes. 

Furthermore, you cannot assume that a human will always be watching the server 
screen, ready to react to dialog boxes or alerts. If an ACG! runs into trouble, it 
should try to recover as best it can and keep going. For example, if a required external 
database shuts down, an ACGl might return an “out of service'’ response to each 
request until the database comes back online. If an ACGI runs out of memory, it 
might simply quit and allow the IFTTP server to launch a fresh copy of it the next 
time a request comes in. Hopefully, that w'oold cure the problem in the short term. 

An efficient, low-overhead ACGI is therefore a windowless, Apple event^aware 
program that posts no alerts or dialogs. It implements only the Apple and File menus. 
For simplicity, die About item in the Apple menu does nothing except show the name 
of the ACGI (although there’s nothing to stop you from implementing an About liox 
if you want to). The File menu contains the single item Quit. A log file is used to 
record all infonnational, error, and debugging messages. 

As shown in Listing 1, the main program starts by caUing ACXiIIoit to set itself up. 
Then it runs die main event loop, calling ACGIEvent to process each new event, 
until the global gDone flag is set and all threads have completed. The program then 
cleans up after itself by calling ACGIQuit. 

THREADS AND THE MAIN EVENT LOOP 

The presence of threads affects the main event loop shown in Listing 1 in three ways. 
First, the loop doesn’t exit as long as there are active threads. This ensures that all 
threads processing FITTP sender requests complete their work before the ACGI shuts 
down. Second, there are two different sleep times for WaitNextEvent: gThreadSleep 
when threads are running and gldleSleep when they’re not. We need idle time to give 
the threads a chance to run. This means w^e should use a rather small value tor sleep 
when gTh reads is greater than 0. On the other hand, when there are no outstanding 
requests, we should set sleep to a large value to avoid wasting CPU time. The 
exception to diis rule is when you have periodic tasks, in which case you should call 
ACGlSetSleeps in \^'WVV^nit to set gldleSleep to get the idle time you need. 

Third, there’s the inner loop that repeatedly calls YieldToAnyThread. This routine 
causes the Tliread Manager to turn control over to the oldest nmning thread. This 
thread keeps control until it too calls YieldToAnyThread to turn control over to the 
next running thread. This continues until the newest thread calls YieldToAnyThread 
and control returns to the main event loop (see “Concurrent Programming With the 
Thread Manager” in dtrvehp Issue 17). 

It’s important to call YeldToAnyThread frequently inside your request-precessing code, 
usually after you complete a logical step in your processing and no less than every 1 
to 2 ticks of the A/Lacintosh clock (1 tick = l/60th of a second). Don’t bother putting 
your calls to YieldToAnyThread inside a timed loop as wt did in the main event loop. 
Just call it often throughout your code: it’s a very low overhead call. The secret to 
uniform response time to ail requests is not to allow any one thread to hog the CPU, 

YieldToAnyThread is enclosed in a timed loop to give threads enough time to do useful 
work when running on a Power Macintosh, Currently, there’s a context switch from 
native PowerPC mode to 680x0 emulation mode when WaitNextEvent is called. In 
addition, historical reasons guanmtee that WaitNextEvent always waits at least 1 tick 
before it returns. Calling YieldToAnyThread only once per pass through the main 
event loop means that threads would get time only once every l/60th of a second and 
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Listing 1 , The ACGI main program 
// Include files and function prototypes 


static Boolean 
static unsigned long 
static long 
static long 
static long 


gDone = false; 
gThreads = 0; 
gThreadSleep = 4; 
gIdleSleep = 0x7FFFFFFF; 
gWNEDelta = B; 


void main(void) 

{ 

EventRecord theEvent; 

long sleep? 

unsigned long ne xtWNE; 


ACGIInit()? 

while (1gDone [| gThreads > 0) { 
if (gThreads > 0) 

sleep = gThreadSleep; 
else 

sleep = gIdleSleep; 

if (WaitSIextEvent(everyEvent, atheEvent, sleep, nil)) 
ACGIEvent(&theEvent); 
nextWNE = TickCountj) + gMEDelta; 
do { 

YieldToAnyThread(); 

} while (TickCountO <- nextWNE); 

ACGIPeriodicTask()? 

> 

AGGIQuitO; 


3 lot of useful CPU time would be wasted in mode switches* The timed loop could 
result in a thousandfold performance increase — without noticeably affecting other 
applications — for ACGIs running coinpiite-bound threads that frequently yielded* 

THE INITIALIZATION ROUTINE ACGIINIT 

ACGIlnit carries out seven distinct steps to get the ACGI going: 

L Initialize the Toolbox* 

2, Get the name of the log file by calling WT\WGetLogName and then cjpen it. 

3. Check to see that both Apple events and the Thread Manager are present. 

4, Set up the menu ban 

5. Install the Apple event handlers. 

6. Call MTVWGetHTMLPages to build the four generic HTML error pages. 

7, Call V\^\^VInit to initialize your processing environment. 
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If ACGIlnit runs into trouble, it calls ACGIFatal to write an error message to the log 
file and quit. If you run into trouble in W\\T\Tjiit you should write a meaningful 






error message to the log with ACGILog and return a nonzero result code. ACGIIiiit 
will write the code to the log and then quit. 

THE LOGGING ROUTINES ACGILOG AND ACGIFATAL 

Two routines that write zero-terminated strings to the log ’— ACGILog and 
ACGIFatal — are shown in Listing 2. In these routines, gLog is an ANSI FELE"^ 
variable that’s local to the source file acgix. It points to the open log file. 


Listing 2. Logging routines 

void ACGILog(char *msg) 

{ 

DateTimeRec dt; 

ThreadID the Thr ead; 

if (gLog NULL) 

return; 

GetTiine(&dt); 

Get Cu rrentT hre ad(& t heThre ad); 

fprintf(gLog, "%4d/%02d/%02d\t%02d:%02d:^02d\t%0101u\tls\n", dt.year, 
dt.month, dt*day, dti^hour, dt.minute, dt*second, theThread, msg); 
fflush(gLog); 


void ACGIFatal {char '^reason) 

if {gLog J= NULL) { 

ACGILog{reason); 

ACGILog{"That was a fatal error.,.shut down."); 

} 

ExitToShell{); 


ACGILog prefixes each message with the date and time and the ID number of the 
tliread it was called in. The items are tab-separated so that you can later import the 
log into a spreadsheet and sort it by date^ time, or thread ID. This can be usefiil when 
you*re tr)dng to debug an ACGI or gather statistics based on the messages you wrote 
into the log during processing. ACGIFatal calls ACGHvOg to write its message to the 
log and then quits the program immediately without waiting for running clireads to 
complete. It’s meant to be called only from within ACGIInit. 

PERIODIC TASKS AND THE TERMINATION ROUTINE 

ACGIPeriodicTask runs periodic tasks by calling your \^TVWPeriodicTask routine 
and then checking for a nonzero result code (in w^hich case it writes the code to the 
log and, if the code is positive, sets gDone to true). The termination routine ACGIQuit 
is the last routine called by the main program. It shuts down processing by calling 
your WWTVQuit routine and then closes the log. 

EVENT HANDLING IN THE MAIN EVENT LOOP 

Since an ACGI is basically a simple Macintosh application widi no window^s, no About 
box, and only the Apple menu anti File menu (which supports the single item Quit), 
you don’t have to worry about activate and update events, and suspend/resume events 
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only need to set the cursor to in arrow. Keystrokes are important only if they Ye 
Command-key equivalents that might represent a menu selection. This limited event 
handling is c^arried out entirely in the routine ACGIEvent and its small support 
routine DoMenu (for menu and Command-key handling). ACGILog is used to 
report any errors that are encountered. 

ACGIEvent doesn't need to do any special processing at this level to hantUe threaded 
Apple events. It just calls AEProcessAppleEvent like any other application. Details of 
the threading process are hidden away in the Apple event handler that's called in 
response to HTTP server requests. 

APPLE EVENT SUPPORT IN THE ACGl 

I'he ACGI must support the four core Apple events and the custom event sent by 
HTTP servers and must he able to process HTFP events in threads. Here are the 
details of how the ACGI shell implements the required Apple events and the 
threading of die server requests. 

SUPPORTING CORE APPLE EVENTS 

Any application that siippoms Apple events must support the four core events (Open 
Application^ Open Document, Print Document, and Quit Applicarion), as well as any 
custom Apple events needed for conuii uni cation with other yirograms. Because the 
ACGI doesn't have any documents, doesn't do any printing, and dt)es all the 
application inidalizatifm liefnre accepting the first Apple event, it can tlcal with the 
four core events with the single hamller HandleAECore: 

f de fine kQuit Cor eEvent 1 
idefine kOtherCoreEvent 0 

static pascal OSErr HandleAECore(AppleEvent *event, AppleEvent *reply, 
long refCon I 

( 

if (refCon == kQuitCoreEvent) 
gDone ^ true; 
return (noErr); 

} 

The ACXtl sets the handler reference constant, refCon, to kOtherCoreInvent for the 
'oapp', odoc', and ’pdoc* events and to kQuitCoreEvent tor the quit' event. When 
the handler is called, it simply returns noErr if the refC^on is kOtherCoreEvent and 
sets gDone to true if the refC^on is kQoitC^oreEvent. 

THREADING HTTP SERVER REQUESTS 

'The WV\TVQ Apple event class defines a single event ID {'sdoc') to pass requests to 
ACGI programs. This is the event that the ACGI shell responds to. To handle 
multiple serv^er requests at once, the ACGI must process each request in its own 
thread of execution. 

This leads to some complications in the code because the Apple Event Manager was 
designed to have only one event active at any given time. To process multiple Apple 
events in threads, the ACGI will have to suspend each new Apple event in the main 
thread of execution, put each suspended event into its own thread for processing, and 
then let each thread resume its suspended Apple event at the end of processing so 
that replies are returned to the HTTP server. 

The one catch here is that when an event is suspended, the pointers to the event and 
reply data structures become invalid. The ACGI must therefore make copies of the 
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event and reply data structures (and not just the pointers) before suspending an event. 

These copies of the AEDescs are passed into the thread for processing. 

So, the processing flow for threading HTTP ser\^er requests is as follows: 

L ACXxIlnit makes HandleSDOC the handler for I rTlT server requests. 

2. The main event loop (running in the main thread) receives an HTTP server 
request and calls AEProccssAppleEvent as usual. 

3. HandleSDOC (also running in the main thread) receives the Apple event. 

4. If there arc too many threads running or the ACGI is refusing connections, 
the handler immediately returns an HTML page indicating that the server 
request cannot be processed. Otherwise, the handler allocates a handle called 
params to hold copies of the Apple event and its reply. Note that the 
complete data structures must be copied, not just tlie pointers to diem, 
because the pointers become invalid wTen the event is suspended. 

5. HandleSDOC creates a new thread and passes params into it. If the thread 
cannot be created, params is disposed of and the error code is returned, 

6. HandleSDOC increments the count of running threads and then suspends 
die current Apple event and returns. The main event loop is now free to 
accept another server request. 

7. The main event loop regains control and calls YieldToAnyThread almost 
inuuediately. Each processing thread is given time to run, and control 
eventually passes to die new diread, 

8. 7'he new thread begins life by calling SDOCThread. This routine makes 
local copies of the suspended Apple event and its reply and then disposes of 
the params handle that was passed to it by HandleSDOC. 

9. SDOCThread extracts parameters from the Apple event, LTRL-decodes them, 
and dien calls V\T\T\Trocess to process the ser\"er request, MTVT\Trocess 
calls YieldToAnyThread frequendy to give time to other threads and to allow 
the main thread to accept new Apple events. MTen MT\TVProccss finishes, 
it returns a handle containing the HTiML response page. 

10. SDOCThread places the response into its copy of the Apple event reply and 
dien resumes execution of the suspended event. The event in this diread is 
now considered complete. You’re guaranteed that no other Apple event will 
be “current” at this time because HandleSDOC suspends each ntw event 
before any of the processing tlireads are given time to run. 

11, The tlu'ead decrements the global c<)unter gThreads and then returns 
(causing die diread to be disposed of). 

With this processing flow as a guide, the a.ssociated code practically writes itself. The 

HandleSDOC routine is showm in Listing 3. 


Listing Handling HTTP server requests 

static unsigned long gMaxThreads = 10; 

static Boolean gRefusing = false; 

static long gThreadStackSize = 0; 

static ThreadOptions gThreadoptions = kCreatelfNeeded | kFPUNotUeeded; 

(continued on next page) 
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Listing 3« Handling HTTP server requests fconf/nuedj 

typedef struct AEParams { 

App1eEvent eve nt; 

App1eEvent reply; 

} AEParams; 

void SDOCThread(void *threadParain); 

OSErr ACGIReturnHandle(AppleEvent *reply. Handle h); 

pascal OSErr HandleSDOC{AppleEvent *event, AppleEvent *reply, 
long refCon) 

{ 

AEParams** params; 

ThreadID newThreadID; 

OSErr err; 

// [1] Too many threads already running? 
if (gThreads >= gMaxThreads) 

return (ACGIReturnHandle{reply, gHTMLTooBusy)); 

// [2] Should we handle this request? 
if {gDone || gRefusing) 

return |ACGIRetiirnHandle( reply, gHTMLRefused)); 

// [3] OK to run***rnake copies of event and reply* 
params (AEParams*^) WewHandle(sizeof (AEParams)); 
if (params nil) 

return (errAEEventNotHandled); 

{*parains) *>event - *event; / / Copy the data structures... 

{*params)->reply = *reply; // ***not just the pointers to theml 

// [4] Create the thread, passing in the copies of event and reply- 
err = NewThreadjkCooperativeThread, (ThreadEntryProcPtr) SDOCThread, 
(void*) params, gThreadStackSize, gThreadOptions, nil, 
snewThreadlD); 
if (err 1= noErr) { 

DisposeHandle j[Handle] params); 
return (err); 

} 

// [5] Increment the count of running threads and then suspend 
// the current event so that we can accept new events* 

gThreads++; 

ret u rn (AES u s pendThe C ur r e n tEve nt(eve nt)); 


Global variables goicie the actions of HandleSDOC. The maximum number of 
concuJTent processing threads is controlled by gMaxThreads. You can get and set this 
value with the convenience routines ACGIGetMaxThreads and ACGISetMaxThreads. 
If gRefusing is true, the handler will renini the HTML page stored in 
gHTMLRefused and not process the event (you build this page in your custom 
routine YVT\WGetHTMLPages)* You set gRefusing by calling ACGIRefuse. If 
you're really concerned about heap fragmentation, you might want to create a pool 


62 develop Issue 29 March 1997 






of preaJlacated threads during initialization with the number of threads in the pool 
equal to gMaxThreads* 'I'hreads are recycled into the pool, limiting fragmentation. 
This is the approach taken by Grant Neufeld in his ACGI framework (see “Threading 
Apple Events’’ in the April 1996 issue of MacTecb Magazine). 

The globals gThreadStackSize and gTlireadOptions give you control over how 
threads are created. The convenience routines ACGIGetThreadParams and 
ACGISetThreadParams allow you to get and set their values. The default stack size 
of 0 causes the Thread Manager to allocate a 24K stack to each thread. (Thread 
creation options are described in detail in “Concurrent Programming With the 
Thread Manager” in develop Issue 17.) 

If your WWWProcess routine (or any routine that it calls) uses a lot of stack space 
for local variables, you might have to increase the thread stack size. You should do 
this in your MTVMTnit routine. You’ll know if you’re running out of stack space in 
your ACGI because your server computer will usuaUy lock up when a running 
thread’s stack overflows the heap space allocated to it. So remember, if your server 
keeps freezing up or bombing, and you don’t think your code is the problem, try 
increasing the stack size allocated to your threads and then increase the ACGI 
memory allocation by roughly the increase in stack size multipHed by your chosen 
value of gMaxThreads. 

file Thread Manager has routmes that check how much slock space a given 
ihread is using. You could iherefore write o debugging macro that logs the stack 
space remaming before calling YieldToAnyThreod. This could be useful in isolating 
where the problem is after the crosh — but it wouldn't actually stop the thread From 
exhausting its stack space becouse that happens between yields. * 


HTTP REQUEST PROCESSING 

Each thread created by HandleSDOC won’t start running until the main event loop 
calls YieldToAnyThread. When it’s time for a new thread to run, the Thread Manager 
saves the state of the thread that just yielded, sets up the new thread’s environment, 
and then calls SDOCThread. This routine is where all the real work of the ACGI 
takes place — and where your custom processing routine \\TVA\T?rocess is invoked. 

SDOCThread is the longest and most complicated routine in the ACGI. It’s 
responsible for extracting all request parameters, LTRL-decoding the search and post 
arguments, packing the parameters into a WT'VTV^equest data structure, calling 
WWT\Trocess to process the request, placing the HTML response page into the 
server reply, and then resuming the Apple event to send the reply back to the server. 

Before looking at the code, it’s a good idea to go over exactly what’s packed into the 
’sdoc’ Apple event. A client brow^ser asks the server to run an ACGI either by 
referencing the ACGI’s CTRL or by submitting HTML form pages that specify the 
ACGI as its action. 

A direct reference is just the URL of the ACGI: 
http://WWW,test.com/test.acgi 

To invoke an ACGI as the action of a form, you need to write HTMl.r code like tiiis: 

<FORM HETHOD=GET ACTION="http;//www.test.com/test.acgi”> 

,..form input items.., 

</FORM> 
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or similar code for METHOD=POST. In both cases, you can supply extra arguments 
to the ACGl by adding them to the end of the URL like this; 

http I / /www, test • com/test * acgiSpatii_args?searcJj_args 

The path ar^iments are everything between the dollar sign (S) and the question mark 
(?), while the search arptmmts are everything following die question mark. The order 
of the $ and the ? are important. If you put the ? before the $, everything following 
the ? (including the $ and what comes after it) is considered part of the search 
arguments, 

V\Tien you're using forms, you can specify a method of either GET' or POST. All of 
your fonn's input variables are URL-encoded, If you specify GET, the input variables 
are tacked onto the end of the search arguments; if you use POST, they're placed into 
a separate parameter called the post argtmimts and sent separately, 

URL encoding isn't particularly fancy, All it means is that the input field names and 
field values are written out as na?tfe=vakic pairs, and all such pairs are placed into one 
long parameter with each pair separated from the next by an ampersand (&), All 
spaces in the original input variables are replaced by plus signs (+) and any special 
characters are replaced by their ESO-8859 Latin^l hexadecimal equivalents in the 
form %xx (where xx represents the two hex digits identifying the character)* 

Any or all of these arguments (if present), along with a series oF jiarameters tliat 
describe the client Ijrowser and the server, are placed into the ’siloc' Apple event and 
sent to the ACGI by the MThP server. Each parameter is iilenriiled in the Apple 
event by 4-character keyword names. The ACGI passes these keyword names to the 
Apple Event Manager to extract the various parameters* 

For a full description of the keywords, refer to Planning and tAanag'mg Web 
on tfre Macintosh: T/ie Complete Gu/de fo WebSTAR and MocHTTP, Chapters 
1 3 and 15. * 

The five most important keywords to be aware of are as follow'S: 

• kPatiu^rgsKeyword — the parameter that contains the path arguments (the 
text between the $ and the ?) 

• kSearchArgsKeyword — die search arguments (everything after the ?) 

• kPostArgsKeyword — the post arguments 

• kUserAgentKeyword — the name and version of the l)rowser that made the 
request 

• IcMethodKeyw^ord — the name of the method (such as GET, POST, 

ACTION) by which the ACCtI was called 

The path, search, and post arguments hold the data that makes up a request. The 
browser name lets you decide which HTML features you mighi want to include in 
your response page. For example, you might not want to use the latest HTML 
features of Netscape Navigator"'^ in your response page if the browser name says that 
the client is an old version of Mosaic that doesn't understand tables and frames. 

Most of the code in SDOCThread (excerpted in Listing 4) deals with extracting 
parameters from the event and then breaking up the search and post arguments into 
name=vahie pairs. 
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Listing 4. The SDOCThread routine 

static void SDOCThread(void *threadParam) 

{ 

WWWReque s t reque s t f 

Size spaceNeededi responseSize; 

OSErr err; 

// [1] Copy event and reply to local storage, 

AEParams** params = (AEParams**) threadParam; 

AppleEvent event - [*parains)->event ; 

Apple Event reply = (*parains)->replY; 

DisposeHandle((Handle) params); 

// [2] Initialize request structure, 
memset {& request , 0, sizeof(request)); 

// [3] Allocate storage for params/args* 
spaceNeeded = ACGIParamSize(&event}; 
request,storage = NewHandleClear{spaceNeeded); 
if (request,storage “ nil) { 
char msg[128J; 

sprintf(msg^ ’‘SDOCThread: no storage memory: %lu bytes,”, 
spaceNeeded); 

ACGILog(msg); 

err = ACGlReturnHandle(&reply, gHTMLWoMemory); 
gDone = true; 
goto Done; 

} 

HLockHi(request,storage); 

// [4] Copy params/args into position, 
err = ACGICopyArgs(&event, trequest); 
if {err noErr} goto Done; 

// [5] Decode URL-encoded search and post arguments, 
if (strlen(*request,storage + (long) request,searchArgs) > 0) { 

err = ACGIURLDecode(*request,storage + (long) request,searchArgs, 
^request,searchNum, ^request,searchNames, 
&request,searchValues); 
if (err 1= noErr) goto Done; 

} 

if [strlen{ request*storage + (long) request.postArgs) >0) { 

err = ACGIURLDecode{*request,storage + (long) request,postArgs, 
^request . postRum, & request. postfJames, 

£frequest,postValues); 
if {err noErr) goto Done; 

HtJnlock( request, storage); 

(continued on next page) 
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Listing 4- The SOOCThread routine (continued) 

// [61 Mlocate HTML response, 
request,response = HewHandleClear(gHTTPHeaderLen); 
if (request,response == nil) ( 
gDone = true; 

err = ACGIReturnHandle(&reply, gaTMLKoMemory); 
goto Done; 

} 

BlockMoveDataJgHTTPHeader, ^request,response, gHTTPHeaderLen); 

// [7] Call the custom processor, 
err - WWWProcess(^request); 

// [8] Put the response into the reply and resume the Apple event. 
Done: 

if {request.storage 1= nil) DisposeHandle(request.storage); 
if (request.searchNames 1= nil) DisposeHandle(request.searchKames); 
if (request.searchValues 1- nil) DisposeHandle(request.searchValues); 
if (request.postNames i= nil) DisposeHandle(request.posOames); 
if (request,postValues \= nil) DisposeHandle(request.postValues); 

responseSise = GetHandleSize{request.response); 
if (err == noErr && request.response 1= nil 
&& responses!ze > gHTTPHeaderLen) 
err = ACGIReturnHandle{6reply, request.response); 
else 

switch (err) { 

case errWWWSoMetnory! 

err = ACGIReturnHandle(Sreply, gRTMLNoMemory); 
break; 

case errWWWRefused: 

err = ACGIReturnHandle{sreply^ gHTMLRefused); 
break; 

case errWWWTooBusy; 

err = ACGIReturnHandle(&reply, gHTMLTooBusy); 
break; 

case errWWWUnexpected: 

err = ACGlReturnHandle{sreply, gHTMLUnexpectedError); 
break; 
default: 

err = ACGIRe tur nH andle(& reply, gHTMLUnexpec tedE rr o r); 
break; 

} 

if (request,response 1= nil) DisposeHandle(request,response); 

// [9] Put error code into the Apple event (if needed), 
if (err \= noErr) { 

long errorResult = err; // Must be long integer- 
AEPutParamPtr(&reply, keyErrorNumber, typeLongInteger, 

&errorResuIt, sizeof(long)); 

> 

fconh'nued on next page) 
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Listing 4* The SDOCThread routine (continued) 

// [10] Resume the event, decrement running thread count, write to 
// the log, 

AE Res umeTh eC u rre ntEven t{& ev ent, £ rep1y, 

{AEEventHandlerUPP) kAENoDispatchi 0)i 

gThreads —; 

ACGILogC’Done,"); 

return; 


'The only item passed to your custom W\^^Trocess roiitine is a ptiinter to the 
WW WReq nest Record, You access the items stored in the record using the convenience 
routines tliat are defined later* 

EXTRACTING PARAMETERS FROM THE APPLE EVENT 

The routines ACGIParamSize and ACGICopyArgs repeatedly call the Apple Event 
Manager to get the size and the text of each parameter, ACGICopyArgs moves each 
successive parameter into the request .storage handle in the WTVWRequestRecord 
data structure (see acgi.h). It also places the offset of each parameter, relative to the 
start of the handle, into corresponding pointer variables in request. Because most 
parameters are only 10 to 100 bytes in length, it seemed far more efficient to pack 
them all into a single handle, d1iis avoids the overhead of making multiple calls to 
the Memory Manager to allocate one handle for each parameter and then make 
multiple calls to liLock and MUnlock when manipulating the parameters during 
processing. 

Another way of storing the parameters is to pbee each porameter Into \h own 
handle. See Jon Norstad's Mail Tools code (available at htlp://chaHoHe.acrs.nwu*edu/ 
mo iltool s/tec hi nfo.html) for an example of this other approoch.* 

All parameters are stored as text strings, even the ccmnecdon ID (a long integer). 
Missing or empty parameters are stored as zero-length strings so that the ACGI can 
handle requests from HTTP servers that only partially implement the full VVA\TVQ 
Apple event suite (diere^s no guarantee a given server program will pass your ACGT 
all the parameters defined in the suite). You can get the numeric value of any parameter 
by calling the convenience roudne HTTPGetLong. 

DECODING URL-ENCODED POST ARGUMENTS 

The search and the post argument strings are URL-decoded by the routine 
ACGIURLDecode following the prescription outlined in Chapter 13 of Plamimg 
and Managing Web Sites on the Macintosh: The Complete Guide to WebSTAR and 
MacHTrP, 

dTie routine begins by counting all of the name-value pairs in the given string by 
looking for & separators. Two handles are then allocated to hold the char* pointers- 
The string is then scanned, and the offset of each argument name and its associated 
value are recorded in the arrays. Finally, the roudne ACGIDecodeCStr is called to 
convert each ?mm£=value pair from ISO-8859 Latin-1 encoding to die standard 
Macintosh Roman encoding. The conversion table used by the popular Netscape 
Navigator browser is employed here for compadbility If you want to substitute 
another 256-character transladon table, you’ll need to replace the ID=1()(K1 ’xlat' 
resource located in the resource file acgi.rsrc. 
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CONVENIENCE ROUTINES 

There are three sets of convenience routines that allow you to extract parameters 
from a server request, build your HTxML response page, and fine-tune the runtime 
performance of the ACGI. 

PARAMETER AND ARGUMENT EXTRACTION ROUTINES 

Seven routines, identified by the prefix “HTTP/* can be used to extract parameters or 
post and search arguments from the WWUTRequestRecord that’s passed to the 
VVT\T\Trocess routine. The enumeration WWWTarameter contains the name by 
which an individual parameter must be referenced: 

typedef enum WWWParaineter { 
ppathargs - 0, 
p_usernaine, 
p_password, 
p_from_user, 
p__client_address, 
p_server_name, 
p_server_port, 
p_script_name, 
p_content_type, 
p_referer, 
p_iiser_agent, 
p_action, 
p_action_path, 
p_method, 
p_client_ip, 
p_full_request, 
p_c 0 nnec tion_id 
} WWWParameter? 

Following are descriptions of the routines. 

Boolean HTTPLockParams(WWWRequest r); 

Locks down the request parameters. Several items in the WVV"\\TlequestRecord are 
stored as handles and musi: be locked down before the ACGI can access them. 
HTTPLockParams locks the items down for you and H'^PPUnlockParams (l^clow) 
releases them. It might be a good idea to unlock your parameters before calling 
Yi el dTo AnyThread. 

Convenience routines that return const char* pointers to parameters implicitly cal! 
HTTPLockParams to lock down the WWTVReqiiestRecord before they return die 
pointers. Note that the request record remains locked when the routines remrn. The 
routines that copy parameters and arguments into the character strings you pass in 
will lock the request record while they’re copying the information and then unlock it 
before they return (but only if the data structure wasn’t already locked on entry), 

void HTTPUnlockParams(WWWRequest r); 

Unlocks the request parameters. 


const char *HTTPGetParam{WWWRequest r, WWWParameter par)? 

Gets a pointer to one of the parameter strings. This leaves r locked. 
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Boolean HTTPGetLong(WWWRequest r, WWWParameter par, long 

Gets the integer value of a parameter. The result is returned in i. The routine returns 
false if the parameter is not an integer. 

Boolean HTTPCopyParam{WWWEeqnest r, WWWParameter par, char ^result, long len, 
long *acttialLen); 

Copies tlie parameter text into die character variable result. The length of result is 
in len; the actual length of the parameter is returned in actualLen. The routine 
returns false if the parameter identifier par is invalid. 

long HTTPGetNumSrchArgs(WWWRequest r); 
long HTTPGetHiimPostArgs{WWWRoquest r); 

Gets the number of search or post arguments. 

Boolean HTTPGetSrchArgAt{WWWRequest r, long index, char *name, long nameLen, 
long *actualNameLen, char *value, long valueLen, long *actualValueLen)j 
Boolean HTTPGetPostArgAt(WWWRequest r, long index, char *nanie, long nameLen, 
long *actualMameLen, char *value, long valueLen, long *actualValueLen); 

Gets a search or post argument by absolute posidon, index is between 1 and the total 
number of such arguments, name receives the name of the argument at posirion 
index, and value receives die value. The lengths of the character array’s name and 
value are in nameLen and valueLen, The actual lengths of the items are returned in 
actualNameLen anti actualValueLen. The roudne returns false if index is out of 
range. 


Boolean HTTPGetSrchArgCount{WWWRequest r, char *name, long *numValues)? 

Boolean HTTPGetPostArgCount{WWWRequest r, char *nanie, long *numValues)j 

Gets the number of search or post arguments that have the field name name. The 
number is returned in numValues. The roudne returns false if thereno search or 
post argument called name. 

const char *HTTPGetMultipleSrchArg{WWWRequest r, char *name, long index)? 
const char *HTTPGetMultiplePostArg{WWWRequest r, char *name, long index); 

Tries to get the instance index of a muldvalued search or post argument. The roudne 
returns an empty string if index is out of range or if name doesn’t exist. The routine 
leaves r locked on exit, index starts at 1. 

Boolean HTTPGetLongMultipleSrchArg(WWWRequest r, char *naine, long index, 
long *i); 

Boolean HTTPGetLongMultiplePostArg(WWWRequest r, char *name, long index, 
long *i); 

Gets the integer value of the instance index of a multivalued search or post argument 
called name. The routine returns the value in i, and returns false if index is out of 
range or the argument is not an integer, index starts at 1. 

Boolean HTTPCopyUultipleSrchArg(WWWRequest r, char ^name, long index, 
char *value, long len, long *actualLen); 

Boolean HTTPCopyMultiplePostArg(WWWRequest r, char *nanie, long index, 
char lvalue, long len, long *actualLen)? 
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Copies the contents of the instance index of a multivalued search or post argument 
called name. The routine returns text in value* The length of the value string is in 
len; the actual length of the value string is returned in actualLen. The routine 
returns false if index is out of range or name doesn't exist* index starts at 1. 

HTML PAGE COMPOSITION ROUTINES 

There are ten routines, all prefixed with “HTML,” to help you compose the HTML 
response pages. The routines that allow you to append different types of data to the 
response page are shown in Table 1; tlie handle to the response page is obtained by 
calling HTMLGetResponseHandle. 


Handle HTMLGetResponseHand1 e(WWWReque st r); 

Gets the handle to the HTML response page. 

OSErr HTMLClearPage[Handle r); 

Clears the current response page (except for the HT FP header) and starts oven 


Table 1, Routines that append data to the HTML response page 


Routine 

OSErr HTHLAppendHandle{Handle r, Handle h); 

OSErr HTMLAppendTEXT(Handle r, long iTEXTResID); 

OSErr HTMLAppendStringtHandle r, long iSTRResID); 

OSErr HTMLAppendlndString(Handle r, long iSTRResID^ long index); 

OSErr HTMLAppendFile(Handle r, char ^localFileHame); 

OSErr HTMLAppendCString(Handle r, char *cString); 

OSErr HTMLAppendPStringfHandle ri StringPtr pstring); 

OSErr HTMLAppendBuffer(Handle r, char *buffer, long len); 


Appends to response page 

Contents of hondle h 

TEXT resource with ID ilEXTResID 

SIR resource with 10 iSTRReslD 

String at location index in $TR# resource 
with ID iSTRResID 

Local text He 
C string 
pQscol string 

Text buffer of length bn 


ACGI RUNTIME-TUNING ROUTINES 

There are 13 routines that allow you to fme-tune the runtitne behavior of the ACGI 
without having to modify the code in acgi.c or directly set global variables* 

VOid ACGIS hutdown(void) 

Shuts down the ACGI as soon as all current threads are finished. 

Boolean ACGIIsShuttingDown(void) 

Tests whether the ACGI is shutting down* 

Boolean ACGIRefuse(Boolean refuse) 

Sets whether to accept or reject requests* 

unsigned long ACGIGetRunningThreads(void) 

Gets the number of active threa ds* 
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unsigned long ACGlGetMaxThreads(void) 

void ACGISetHaxThreads{unsigned long newThreads) 

Gets or sets die maximum number of threads allowed to run at the same time. 

void ACGIGetSleeps[long *whenThreads, long ^whenldle) 
void ACGISetSleeps(long whenThreads, long whenidle) 

Gets or sets the sleep settings. 

long ACGIGetWNEDelta(void) 

void ACGISetWHEDelta(long newDelta) 

Gets or sets the time between calls to WaitNextEvent. 

void ACGIGetThreadParams(Si 2 :e *stack, ThreadOptions ^options)? 
void ACGISetThreadParains(Size stack, ThreadOptions options); 

Gets or sets the thread stack size and creadon options. 

const char *ACGIGetHTTPHeader(void) 

Gets a pointer to the standard HTTP header. 

CUSTOMIZABLE ROUTINES 

The six customizable roudnes in www.c allow you to adapt the ACGI shell to suit 
your needs. Fve supplied simple, straightforward samples of the routines in the tile 

WWW.C- 

The default version of the WWVVTrocess routine is shown in Listing 5. It returns a 
page that displays all of the HTTP server request parameters in a nicely formatted 
table. Note the use of the YIELD macro here. It provides a convenient way of 
yielding to other threads and automatically aborting should the ACGI signal that it 
wants to quit. 


Listing 5, The default version of WWWProcess 

#defioe YIELD() { YieldToAnyThread(); \ 

if (ACGIIsShuttingdown()) \ 
return (errWWWRefused); } 

OSErr WWWProcess(WWWRequest request) 

{ 

Handle r = HTMLGetResponseHandle(request); 

char s[1024], najne[512], value[512]; 

long len, i, n, iName, iValue; 

Boolean gotOne; 

OSErr err; 

// Build a table to display the WebSTAR request parameters, 
err - HTMLAppendPString(r, 

" \p<HTML><HEAD><TITLE>ACGI</TITLE></HEAD>\r\n'^) ; 

(continued on next page) 
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Listing 5* The default version of WWWProcess (continued) 

YIELD(); 

err = HTMLAppendCString{r^ 

"<B0DY><H1>AGGI ParameterB</Hl><TABLE BORDER=0>^); 

YIELD{); 

err = HTMLAppendCString(r, 

’^<TK><TD ALIGN=RIGHT NOWRAP><B>Path arguments:</B></TD><TD>; 
YIELD{); 

if {HTTPCopyParam(requestI p_path_args, s, 1023, &len)) 
err = HTMLAppendCStringjr, s); 

YIELD 0? 

// and so on, for all the other parameters 

// Now show all the search arguments, 
err = HTMLAppendCString(r, 

"</TD></TR><TR><TD ALIGN^RIGHT NOWHAP VALIGN^TOP>" 

^^<B>Search Arguments:</B></TD><TD>"); 

YIELD(); 

n = HTTPGetNuiRSrchArga (request); 
if (n > 0) { 

for (i = 1? i <= n; i++) { 

gotOne = HTTPGetSrchArgAt(request, i, name, 511, fiiName, value, 

511, siValue); 

if (gotOne) { 
if (i > 1} 

err ^ HTMLAppendCString^r, "<BR>"); 
err = HTMLAppendCString{r, name); 
err = HTMLAppendCString(r, " = "}? 
err - HTMLAppendCString(r, value); 

} 

YIELDt); 

} 

} 

else 

err = HTMLAppendCString{r, "{none)"); 

// and similarly for the post arguments 
err = HTMLAppendCString[r, 

"</UL></TD></TRx/TABLE>\r\n</BODY>\r\n</HTML>\r\n" ); 
return (err); 


OVER TO YOU 

That’s about it for writing threaded, high-performance ACGIs in CT bet you 
thought it was a lot more difficult than this, didn't you? 

A threaded ACGI written in a high-level language offers a significant performance 
increase compared to an equivalent ACGI written in AppleScript. IfyouVe been 
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using AppleScript exclusively to do your HTML form processing, I hope this artide 
will whet your appetite to try scjtiiething a bit more daring. It’s time to kick your Web 
site into high gear and move it over into the fast lane! 
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ACCORDING TO 
SCRIPT 

User Interactions 
in Apple Event- 
Driven Appikotions 


CAL SIMONE 


So far throughout the histor}^ of the Macintosh, most 
applications have been designed to be run by a user 
double-clicking the icon of an application (or document) 
in the Finder and manipulating the application and its 
data through the graphical interface. Recently, the 
publishing industry has adopted AppleScript and 
scriptable applications as die mechanism for creating 
production systems. Now that scripting and Apple events 
have become more pen^asive, and more and more 
applications are scriptable, applications must be preparetl 
to be controlled remotely by iVpple events from odier 
a[)plications and scripts. And there's a new kind of 
applicarion on the horisi^on, the Apple event-based 
{tppluvitwn. A server application has no user interface: it^s 
designed to communicate with the outside world only 
through Apple events. Although serv^er appLieations have 
been possible to w'rite since the inti'oduction of System 
7, they’re becoming increasingly important and will 
play a major role in the future versions of the xMac OS. 

In other words, there may not be a human being sitting 
at the computer where your application is running. 

In this column, Til cover these topics: 

• the two types of Apple-event control 

• determining wiien your application should interact 
with a user 

• how^ to interact, when a user is present 

• how not to interact, wiien no user is present, and 
how to return errors when you don’t interact 

There are some important differences between direct 
manipulation through the graphical interface and remote 
control through interapplication communication. When 


developing server applications, you’ll want to be careful 
about w^hat happens w hen an Apple event (or series of 
Apple events) takes over. This applies not only to 
applications that are designed to be controlled primarily 
through Apple events, but also to those designed to be 
controlled mainly through a graphical interface but for 
which Apple events provide an alternative interface to 
the graphical one. The information presented in this 
column apphes to both types of application. 

TYPES OF APPLE-EVENT CONTROL 

For this discussion, I’ll classify Apple-event control into 
two scenarios: 

• Simulating a user sitting at the computer — Many 
users will write scripts that help them automate their 
work. They’ll generally still be at (or near) the 
computer wiien the scripts run. In such cases, it’s OK 
(or even expected) that an application will interact 
with the user whenever there’s a problem or a choice 
needs to be made, or when the computer needs more 
input. Many scripts that drive such applications will 
even incorporate interaction in the form of dialog 
boxes. This scenario is often the case for embedded 
scripts, such as tht^se anached to tool palette icons. 

9 When a user isn’t present — This is die more 
interesting case for automation and integration 
through intera|ipI i caticm communication, and wi 11 
become increasingly common as more intelligent 
scripts are written. Some operations (and some 
applications) are more suited dian others for 
unattended batch processing. It’s recommended for 
operations chat take a long time, such as those found 
in production systems; in these situations, direct 
interaction with the user is usually not a good idea, 
since no one’s likely to he there to deal with a 
problem or a request for more information. Server 
applications deal only with this scenario. 

Since your application may need to respond to either 
type of Apple-event control, Til describe how to 
comfortably handle both, starting with the w^ay to 
detennine which one youVe dealing with at a particular 
moment. The largest issue to tackle in responding to 
Apple events is wdiedier to interact with the user. I’ll 
explain how to determine whether you should interact 
and what to do once youVe made that determuiation. 
Incidentally, in a standard factored application (you are 
factoring your application these days, aren’t you?) you 
can get most of the proper behavior for free. 


CAL SIMONE (rTTainevent@hES.com[ eots, drinks^ and sfeeps 
AppleScript. Just when he thought he was out of the woods, the 
AppleScript Language Association |ASLA) wos born. Oh welt, 
maybe next year hell get to take that vacation. And why didn't Cal 


write a column for the last couple of issues of develop^ Let's see., 
his company shipped a product, ar^d he porticipoted in six trade 
shows, moved to a new apartment, and solved the world hunger 
problem (just kidding about that last one}.* 
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An example scenario. Let’s look at a common case 
that may or may not require user interaction: handling 
the Core suite’s Close event. According to the Apple 
Event Registry, one of the optional parameters for this 
event is the saving parameter, which can have one of 
three enumerated values: yes, no, and ask. The 
traditional meanings of these values are as follows: 

• yes will always save a modified document, presenting 
a standard file dialog if it has never been saved 
(unless the user included the saving in parameter to 
specify where to save the tiocmnent). 

• no will never save a modified document, but rather 
discard any changes. 

• ask will allow the user to choose whether to save the 
document, invoking the user interface behavior. 

But it’s not quite that simple. For example, assume that 
the user modifies a document in one of your application’s 
windows and then runs a script that executes the 
command close the front window (with no saving 
parameter or with saving ask). Your application’s Cltjse 
event handler will typically display a dialog box asking 
the user whether to save the document. The catch is tliat 
you can’t always do this; it depends on where the script 
is mrming. Yon could implement a preference setting 
that allows the user to configure your application for 
“response to humans vs, non-humans,” but having too 
many preferences spoils the simplicity. 

So what should you do? The solution is to call the 
routine AEInteractWithUser, and then decide what to 
do based on its return result. But before getting into 
that, we’ll take a look at how the Apple Event Manager 
decides whether user interaction is appropriate. 

BEHIND THE SCENES 

The following conditions are considered by the Apple 
Event Manager to determine whether you should 
interact while handling an jVpple event. Note that the 
first one is an application setting, while the last two are 
optional attributes of a particular event that may be set 
by the sender. 

• the user interaction level ^— whether your application 
allows interactions in general 

• the event source attribute — where the particular 
Apple event came from 

• the event’s interaction-requested attribute — whether 
the Apple event wants you to interact 

The user interactian level. The Apple Event Manager 
first checks the mer interactioji level of your application. 
You can call AEGetInteractionAllowed yourself to 
determine w^hich Apple event sources can cause your 


application to interact with the user. If you need to 
change the interaction level, you can set it at any time 
with AESetlnteractionAlIowed, 

The Apple Event Manager provides a data type, 
AEInteractAllow'ed, which is an enumeration that 
defines three levels of allowable interaction: 

• Interact with self— At this level, you can interact 
with the user only in response to Apple events 
you’ve sent to yourself, through your factored user 
interface or from an attached or embedded script 
that you’re executing inside your application. 

• Interact with locail — You can interact with the user 
in response to Apple events originating from the 
same computer where your application is running. 
This includes the above case. 

• Interact with all — You can interact with the user in 
response to any Apple event, whether sent from the 
same computer or a remote machine. 

Remote events will arrive only ff all rhe conditions for 
accepting remote events are met. You need to set two flogs in 
the SIZE resource — "accept high-level events" (to receive any 
Apple events) and "allow local and remote events" (to receive 
events from other computers) — and give permission for 
program linking in the Users ond Groups control panel. You 
must also make sure that Program Unking is turned on in the 
Sharing Setup control panel and enabled for the application In 
the FindeYs Sharing dialog * 

There’s a fourth possibility for some applications, the 
true lowest level of interaction, which is “no interaction.” 
This is the appropriate level in a background-onJy 
application or any pure server application, or any other 
situation where interaction is undesirable. Consider 
this example (which Jon Pugh came across when he was 
w^orking for Storm Technologies, while implementing 
scriptability in PhotoFlash): An attached script is 
executed as part of an automation process. The script 
gets an error and the application puts up a dialog box 
— but there’s no one there to answer it. If users can 
execute a script inside your application and the script 
might be run without a user present, you’ll have this 
problem. Before running the script, the user needs to 
be able to tell your application, “No one will be here, 
so don’t interact.” 

Since the Apple Event Manager doesn’t provide support 
for the no-interaction condition (the AEInteractAllowed 
type has only three possible values), you’ll have to set 
up and maintain this yourself. The simplest way to 
implement this setting is by using a global Boolean 
variable for the no-interaction flag- If the variable’s 
value is true and your application is called on to do 
interaction, you’ll know right away not to allow the 


ACCOSDENO TO SCRJPT: USER INTERACTIONS IN APPLE EVENT-DRIVEN APPLICATIONS 75 




interaction* (Note tliat if your application handles 
multiple concurrent Apple events using threading, an 
application global is not a good solution*) 

Because AppleScript doesn’t provide a way to get or set 
Luteraction levels from scripts, you'll need to implement 
a user iuteractioii level property for your application, 
similar to the one in Photo FI ash, that a user can set or 
get from a script This property should handle all four 
enumeration constants and associate the fourth level, 
no interaction, with the global Boolean variable* In 
your ’aete' resource, use the following terminology and 
4-byte codes for the enumeration constants: 

• never interact — ’ eNvr' 

• interact with self — 'elnS' 

• interact with local — elnL’ 

• interact with all — 'elnA' 

Apple evenDi initiated from the user interface should 
prnhahly ignore the no-inreraction flag altogether, and 
just call AEInteraciVVithUser and interact in the usual 
way if need he. This way your application could 
perform dfmble duty, successfully performing actions 
initialed by Apple events from other sources without 
disturbing a user who might be sitting there using the 
application* 

The event source attribute. The next step taken by 
the Api^le Event Manager is to examine the event somre 
attr/hnte of the particular Apple event being liantiled* If 
you want to look at tlie .source for an Apple event, you 
can call AEGctParamPtr with the keyEventSourceAttr 
keyword to obtain the source. The source data type, 
AEEvenrSource, is an enumeration indicating five 
possilile sources: unknown, direct call, same process, 
local process, and remote process. This is checked 
against the user interaction level to find out wdiether 
your application allows user interaction in response to 
an Apple event from this particular source. 

The interaction-requested attribute. Finally, if the 
Apple PIvent Manager determines that interaction with 
the user in response to the event source is OK, it 
examines the event’s interaction-refnestedartfibnre, which 
tells die Apple Event Manager what kinds of interaction 
are requested by the Apple event* If you want to look at 
this level yourself, you can call AECjetParamPtr with the 
keylnteractLevelAttr keyword to obtain the interaction 
level requested by the Apple event. There are three 
constants that represent the interaction levels: 

• LMtAlw'aysInteract — Your application can interact 
with the user for any reason, such as to confirm an 
action, notify the user of something, or request 
information. 


* kAEC an Interact— Your application can interact 
with the user if it needs to request information from 
the user to continue* 

• kAENeverlnteract — Your application should never 
present a user interface while handling this Apple 
event. 

Mdien present, an additional constant that’s set by the 
.sender of the event, kAE Can Switch Layer, contributes 
to determining whether yon may bring yourself to the 
foreground if you need to interact. 

If the interaction-requested attribute is present, both its 
value and the user interaction level (obtained from 
.AEGetlnteractionAllowed) determine w hether you can 
interact* Otherwise, the default rules apply: if the event 
is remote, the default is “never interact”; otherwise the 
default is “can interact.” This default scheme has the 
advantage that the interaction le%'els work out neatly for 
events sent to your application from yourself — that is, 
from attached or embedded scripts running inside your 
application or frtim your factored user interface — 
since the default for events on the same machine is “can 
interact” (Note that die “never interact” value for the 
interaction-requested attrihute is different from the “no 
interaction” user interaction level tlescribed earlier. 

The former is an event attribute set by the sender of 
ihe event, wHiile the latter is a setting in the server 
application.) 

DETERMINING WHETHER TO INTERACT 

So how^ do you make this w^u’k in your application? 
Before initiating user interaction, you’ll neetl to make 
sure your application is the active application ^— that is, 
it’s in the foreground. Let’s take a moment to discuss 
the w^ays to become the active application. 

Ill the old days, shortly after System 7 w as released, 
developers used to call the GecCurrentProcess routine, 
follow'ed hy SetFrontProcess to switch layers* In that 
case, an application won’t actually go to the foreground 
until the next call to WaitNextEvent, which usually 
won\ happen until die application returns to the main 
e%^ent loop. Moreover, you can’t later prevent your 
application from coming to the foreground if youfre 
able to correct a problem and no longer need to be in 
die foreground. Since we’re talking here about the 
situation wfiere you’re in an Apple event handler when 
this happens, don ’f call SetFrontProcess to make 
yourself the active application; there’s no need to do 
this* Developers have also used the Notification 
Manager to put up an alert, beep, place a diamond 
mark in the Application menu, call Mom in Florida, 
and so on. This is somewhat better, but still more 
ditlicuk than it has to be. 
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It turns out that finding out whether you should interact 
with the user and getting yourself into the foreground 
are really easy witli the Apple Event Manager, \Aliat? 
“Apple Event Manager” and “easy” in the same 
sentence? Yes, it’s true! The correct, easy, and fun way 
to do this is by calling AEIiiteractWthUser {which will 
calf the Notification Manager on your behalf to get the 
user’s attention): 

err AEInteractWithUser(timeOutInTicks, 
notificationRec, idleProc ); 

MTiat’s more, this works even in situations where there’s 
no Apple event being handled (whenever you need to 
gratuitously get yourself into the foreground, right where 
you are in your code). 

If AEInteractWithUser returns noErr, you’re in the 
foreground and it’s safe to interact. That’s it! The 
conditions discussed earlier are autoinatically tested for 
you, so you won’t have to do any of that yourself. 

Be sure to check the error that AEInteractWithUser 
returns. If it’s not appropriate for you to interact, 
AEInteractWithUser returns errAENoUserInteraction, 
Also, be aware that AEInteractWithUser can time out if 
timeOutlnTicks is reached before the user responds to 
the notification. You should supply a reasonable timeout 
value for timeOutlnTicks, and if AEInteractWithUser 
times our, return errAETimeout or some other suitable 
error as the result for your event handler. And remember 


that the original Apple event can time out if the 
notification is outstanding for too long. 

If your application might have any windows visible 

when you call AElnterodWithUser, you must use o filter 
procedure to hondle update, activate, suspend, and resume 
events. If you don't do this, you'll lock out other processes from 
getting any processor time. For details, including a description 
of the hazards of failing to use a filter procedure, see Tech note 
TB 37, Tending Update Perils."' 

Listing i shows a very simple routine that calls 
AEIfiteractM^thUser, checking the no-interaction 
flag if requested. You should call this routine before 
every alert or dialog box that you may present, and 
handle the situation another way if you aren’t allowed 
to interact. 

So, in our earlier Close event example, the saving yes 
and saving ask cases work out a little differently than 
you might have expected: if AEInteractWithUser remrns 
noErr, put up the alert or dialog; if not, retum from the 
Close event handler with errAENoUserInteraction, 
errAETimeout, or some other suitable error, 

WHEN THE USER IS THERE 

Now that youVe determined whether or not to interact 
in a given situation, let’s look at a couple of things to 
keep in mind when you put up an alert or dialog box 
while handling an Apple event. 


Listing I - Interacting with a user while handling an Apple event 

FUNCTION AllowlTiteractiori(timeOutlnTicks; Longlnt; checkNoInteractFlag: Boolean): Boolean; 

VAR 

procSerNum; ProcessSerialNumber; 

BEGIN 

(* If the no-interaction flag should be checked and that flag is true# don't allow any 
interaction* *) 

IF checkNoInteractFlag & gNoInteract THEN 
Allowinteraction := false 
ELSE 
BEGIN 

{* After executing the next line# your application should be in the foreground# unless it 
times out, or unless interaction isn't appropriate. Note that gIdleProc is usually your 
Apple event idle proc, *) 

err AEInteractWithUser{timeOutlnTicks# gNotificationRec, gIdleProc); 

IF err <> noErr THEN 

(* errAETimeout # or some other error *) 

Allowinteraction := err = noErr; 

END; 

END; 
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If you end up presenting an alert or dialog box in 
response to an Apple event for which you shouldn’t 
interact (because for some reason you weren’t sure 
whether you should interact or not), it’s best to time 
yourself out by dismissing the dialog after a reasonable 
time, even when no one has clicked any of its buttons. 
You might consider doing this even if interaction is 
allowed; after a lengthy time, pur your application out of 
its misery and move on. Just be careful which button you 
choose —you might want the effect of canceling out the 
dialog, or producing the least damage, or losing the (east 
amount of work. If yon choose to continue processing, 
be prepared to use suitable defaults, if applicable. 

An example of an Apple event scenario that always 
involves interacrion with the user is handling the Edit 
Graphic Object (EGO) event. EGO is an Apple event 
specification devised by Allan Bonadio in 1991, In the 
EGO scenario, an application that contains an embedded 
object that was created by another application allows a 
user to edit the object in the creating application. If you 
do need to pull yourself to the front immediately (such 
as witli EGO), bj^assing any possibility of Notification 
requests, you should call SetFrontProcess tollowed by 
AElnreractWithUser You can insert the following just 
before the call to AEInteractWithUser in Listing 1 (in 
the parameter procSerNum in the GetCurrentProcess 
call needs to be a pointer): 

err := GetCurrentProcess (procSertiuia); 
err := SetFrontProcess(procSerNum); 

Because the Apple event always results from a user 
action, in this situation It’s OK to force yourself into 
the foreground — tliis may be the only reasonably 
significant case where you should do this. 

And, as in the case of AEInteractWithUser, yoo should 
he careful about pending update events wdiile your alert 
or dialog box is on the screen. 

WHEN NOBODY'S HOME 

What if there isn’t a user sitting at the computer? You’ll 
w^ant your application to cope with limitations or 
restrictions on user interacrion without faihiTg, especially 
when it comes to reporting errors properly. 

WTicn your application is more likely to be controlled by 
a liatch process, such as a script that runs periodically in 
a production system, avoid requesting user interaction 
w^hen the computer is likely to be unattended. (W^en 
you’re not sure how you’re being controlled, performing 
the tests discussed earlier in “Behind the Scenes” may 
help you find out.) You don’t w'ant an alert popping up 
on a screen when there’s no one to respond — this can 
cause the computer to come to its knees and, depending 


on what other applications are running, may even cause 
it to stop processing anything else. 

Dealing with the problem yourself* Not being able 
to interact when you want to is a problem that can arise 
from any of the following: yooVe faced with the error 
errAENoUserlnteraction (or your Allowinteracrion 
lunction remms false); AEInteractWithUser times out; 
or you implement “no interaction” as a user interacrion 
level. In some cases, the best thing to do is to try to 
handle die situation yourself. 

If the situation doesn’t require the user to make a 
choice or supply any information — that is, if you just 
want to tell the user something — don’t hold up the 
works for this; simply skip the interaction. But if you 
do require a choice or some information, consider 
handling this situation intelligently in the application. 
Users will have a better experience if they come back 
from lunch (or the next day) to find that your 
applieation carried on instead of stopping after the first 
20 seconds because it needed some small piece of 
information. For example, if an Apple event is missing 
a required parameter, and the inability to put up a 
dialog box means that you can’t request information 
from the user, see W'hether you can use default values 
instead. 

Be careful what behavior you choose when the user 
isn’t available to decide. And don’t go overboard by 
trying to second-guess a user — that can cause genuine 
irritation. If you really, really need to interact but you 
can’t, its acceptable to generate an error such as 
errAENoUserlnteraction. Judge what’s best for your 
application, leased on who uses it and how^ it’s used. 

Returning an error to the Apple event. Sometimes 
the best w^ay to avoid user interaction Is to return an 
error describing what went wrong through your Apple 
event reply For server applications, this is the only way 
to interact. It puts the burden of responsibility in the 
hands of the Apple event’s sender, which is often a script 
or another application running on another machine. 
This way, you’re off the hook — the decision about 
whether to find and disturb a user is made by another 
process. As shown in Table 1, the Apple event error- 
reporting mechanism provides several emrparamettn 
that you can use to more concisely describe the nature 
of die problem. 

It’s important to come up with unique error numbers, 
because the text for the corresponding error messages 
should be localized and thus may vary from location to 
location and system to system. The numbers are the 
best means for the sending application or script to trap 
errors, since they won’t vary. 
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Table 1. Apple event error parameters 


Parameter 

keyErrorString or 
kOSAErrorMessoge 

AppleScript keyword 

direct parameter 

Meaning 

The error messoge text. Strive to keep this cleor and concise. 

keyErrorNumber or 
kOSAErrorNumber 

number 

The error number. Remember that Apple reserves oil negottve 
values, os well os positive values up to 128. 

kOS AE rro rPa rti □ 1 Resu 1 1 

partial result 

If more than one item is being hondled by the Apple event, you 
can return the successful results processed so far. 

kOSAErrorOFfendingObied 

from 

You can indicate which object has caused the problem. This is 
especially useful for coercions. 

kOSAErrorExpectedlype 

to 

in coercions, the type requested in the coercions. 


Note: The AppleScrJpf keywords ore those used in the error and on error commands. 


Normally the error code you return from your Apple 
event handler becomes the error number, so there’s no 
need to explicitly supply an error number parameter. It’s 
better to use the error number as the return value from 
your event handler, rather than stuffing it as a parameter 
in the reply event yourself, because the error code will 
become the return value for the call to AESend in the 
sending application or script, which can immediately 
detect that something went wrong with the handling of 
the Apple event. (Howevetj if you suspend an Apple 
event, you must place the error number explicitly in die 
error number parameter of the reply before resuming 
the event.) In any case, all other error parameters must 
be placed in the reply event w ith AEPutParamPtr or 
x^EPutParamDesc. As an example of setting an error 
parameter, here’s how to provide an error string to an 
Apple event reply: 

err i- AEPutParamPtr(reply, keyErrorString, 

typeChar, @mes sageStr[I], length(mes sageStr)}; 

If you want to cancel an operation, you’ll typically return 
error -128 (userCanceledErr), which is the most 
reliable way to stop executing a script that’s sending an 
Apple event to your application. The exception to this 
rule occurs when the Apple event was sent from a script 
command that’s inside a try block that specifically traps 
for that error; in this case, you may not be able to halt 
the script. 

Note that there are many cases where either you can’t 
return errors or, if you can, they’ll be ignored. An x\pple 
event sent with a send mode of kAENoRepIy doesn’t 
have a reply event. So if you try to stuff parameters 
such as error parameters into this nil reply, you’ll die 
horribly. You can also get a nil reply event if the Apple 
event is sent by an AppleScript command in an ignoring 
application responses block. Furthermore, the Finder 


ignores errors returned to Apple events it sends, such as 
the Required suite’s Open Docmnents event that’s sent 
wEen icons are dragged onto your application’s icon. 
And a aser can trip you up by enclosing an AppleScript 
command in a try block (try,..on error,,.end try); 
you’ll still get a reply event, but the script that executes 
the command can ignore any error inftinnation you 
return in the reply, or ignore your error altogether. 
There’s no specific strategy to follow in these cases, 
since you can’t know when this is happening, but be 
aware that it can happen. 

Supplying a missing data value. Part of the design 
of your error-handling scheme includes deteroiining 
that it isn’t always necessary to return an error. Rather 
than cause an error, sometimes it’s better to return 
noErr and place a Boolean indicator value or an empty 
list in the direct parameter as the result. This depends 
mostly on which xApple event you’re handling. 

For example, if you receive a request to find or use an 
object or a file that doesn’t exist, you should return an 
appropriate error, such as errAENoSuchObject or 
frfErn (The exception to this is the Does Object Exist 
event, where you always want to return a true or false 
value.) On the other hand, if the request is to search for 
all items matching a certain criterion, you may want to 
return an empty list if nothing matches the criterion. 
This way the sending application or script won’t fad, 
and the script can just check the result instead of having 
to trap for errors. 

OUT ON GOOD BEHAVIOR 

Wlien a user is likely to be at the computer while a 
script controlling your application is run or while 
another application is directly communicating w'ith 
your application, interacting with the user can be 
appropriate. Although having the application bring up 
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alerts and dialogs used to be the norm, it's becoming 
rarer. Since scripts can interact with a user, why not let 
the script do the user interaction when it needs to? 

The techniques Fve described in this column apply 
whether Apple events are an alternative to the graphical 
interface or your application is designed specifically as 
an Apple event server application. If your application 
will be controlled through Apple events, decide when 
it*s appropriate (and when it"s not appropriate) to 
interact widi the user, by performing the tests discussed 
in this column, A well-planned interaction and error 
code-and-inessage scheme can make it possible for 
users to run your application in situations where a user 
isn't in cootroL 


RELATED READING 

• hside Macintosh: Interapplicafion Communicotion 
by Apple Computer, Inc. (Ad dt son-Wes ley 1993), 
especially Chapter 4, "'Responding to Apple 
Events:" 

• Apple Event Registry: Standard Suites (Apple 
Computer, Inc., 1992). 

• Technote TB 37, "Pending Updote Perils." 


Thanks to Andy Bachorski, Sue Dumont, and Jon Pugh for For recently updated vocabulory advice from Cal, see 

reviewing this column." this issue's CD or deve/op's Web site, under Additional Articles." 
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Using Newton Internet Enabler to Create a 
Web Server 


With Newton Internet Enabler (NIE), a whole host of TCP/IP-based 
applications become possible on the Newton. Internet clients for e-mail, 
Web browsers, and otha~ common services are springing tip, and 
developers are using NIE to provide portable access to legacy systems 
and databases. But how do you get started? This article will explore the 
details of using NIE by presenting a sample Internet application — 
a working Web server. 



RAY RISCHPATER 


The long-awaited Newton Internet Enabler (NIE for short) opens up the Internet to 
Newton users — the personal communications platform can now speak TCP/IP to the 
rest of the world* With so many possible apphcations that could use it, progTainming 
under NIE is not only useful, it^s sure to be a lot of fun! 

Fve chosen to introduce NIE by looking at a sample application called nl FTIPd — 
a Newton-based Web server that implements tlie iriTP protocol. Throughout the 
articlcj ril assume youVe familiar with the basics of Newton software development 
and TCP/IP; see the Nanton Guide and the NIE documentation for 

reference, 

SAMPLE APPLICATION BASICS 

Before delving into the sample application, let's take a moment to see what's included 
in NIE, NIE provides support for three distinct entities. There's a Link Controller 
for sharing an underlying link (that is, the low-level PPP or SLIP connection) 
betw^een multiple applications and perfonning expect-response scripting* It also 
provides a Domain Name Service (DNS) to map back and forth betv^een host names 
and IP addresses. Finally, of course, there's an implementation of TCP and UDP 
through NewtonScript's endpoints. Eor details of how the different parts of NIE 
work, see “NIE in a Nutshell.” 


Our sample apphcation (whieh accompanies this article on this issue's CD and develops 
Web site) is a bare-bones HTTP version 0.9 server. To help you understand the code, 
here are the basics of the HTTP 0*9 protocol: 

• Objects (usually Web pages) are referred to by a URL, which is a concatenation 
of the protocol being used (http), the host name serving the document 
(such as WWW* lothlorien*corn), and the path and filename of the document 


RAY RISCHPATER (ray_rischpaJer@Qllpen.coni) 
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NIE IN A NUTSHELL 


NIE's Link Controller is responsible for establishing the link 
and passing a prepared link to the SLIP or PPP manager 
for the TCP/IP stack to use* In NIE 1.0, authentication is 
necessary before the stream is switched to PPP — there 
is no support for PAP or CHAR The only Internet links 
supported in NIE 1 *0 are PPP or SUP over serial or modem 
links* [NIE 1.1 odds support for PAR CHAR and interactive 
authentication.) There's a setup utility for users to enter 
information about their Internet service provider, such as the 
access number, link-level protocol, and a connection script* 

The NIE 1.0 DNS is admittedly austere* You can map host 
names to IP addresses and the reverse, or you con look 


up a mail server for a porticular host, but less common 
kinds of queries are not supported. Name resolution is 
nonrecursive -“NIE won't resubmit queries based on 
earlier responses. Mappings are cached for a period of 
time to minimize repeated network queries. If your 
application requires more general domain name 
functionality, you'll find yourself writing your own, but 
for most applications this shouldn't be necessary. 

Access to TCP or UDP sockets is available through the 
standard endpoint API, with new options to support the 
different things you may wont to do with such on 
endpoinh 


being sensed {such as far the root document). A typical URL is 
http ;//www. 1 othlorie n-CO m/. 


• Objects are fetched with the GET instruction. A request comes in containing 
the word GET followed by the partial URL (the path and filename^ but not 
the protocol or host name) of the {object being fetched, followed by a carriage 
return and linefeed pair. For example: 


GET / 


• Form data can be retrieved with an extension of the URL: the URL is followed 
by a quesrion mark and some text. Widiin this text, field names may he 
declared to the left of an equal sign (=), with the data in the field to the right 
of the equal sign, although data is not required. Multiple field declarations 
are separated by an ampei-sand (&). .4 form mth two fields might look like 
this: 


GET /myapp/ search. html ? f ield l=hel loS f ield2^orId 

In response, the HITT server dynamically creates a response object thads 
returned to the client. 


For the latest version of the ssmpte oppTicotion, check oul the lotesi CD and 
develop's Web site, as this code is perpetually evolving.* 


HANDLING REQUESTS 

Since the Newton doesn’t have conventional directories or files, we need to make 
some compromises to translate directory- and file-oriented specifications into 
something more meaningful on a Newton. My implementation uses a registry to 
correlate Newton data (such as appltcation soup entries) with translators capable of 
creating Web objects from Newton data. These translators convert frames or soup 
entries to HTML or pure text, and nHTTPd has an API with three methods to 
allow other programs to register as translators: 

• nHTTPd:RegTransIator(inAppSym, inPathStr, inCallbackSpec) registers the 
callback specification frame inCallbackSpec for your application (whose 
application symbol is iiiAppSym) and the partial URL path indicated by 
inPathStr. (More about the callback specification fi:‘amc in a moment.) It’s 
strongly urged that you use a path beginning with your application symbol to 
prevent collisions in the path name space. 
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• nH'rrPd:UnRegTmnslator(iriAppSym, inPathStr) removes the callback 
specification frame for the partial URL path indicated by itiPathStr* 

• nHTTPcl:UnRegTranslators(inAppSym) removes all registered translators 
for the application whose symbol is inAppSym, 

The callback specification frame provides a mechanism for nlTrFPd to invoke 
a translator and has the same format as a regular commimications callback 
specification. The only required slot is a CompletionScript slot (since all calls are 
asynchronous), containing a hinction that is passed, in order, these three arguments: 

• inEp, the endpciint associated with the request 

• inData, a frame containing the data received from the client 

• inErr, an error cotie, or nil if the request began with no errors 

The inData frame has at least four slots: 

• raw is the original partial URL. 

• data is the partial URL without tlie path. 

• path is the path of the partial URL withtmt the filename. 

• tag is the partial URL with neititer path nor any form data. 

A form slot, if present, contains slots named for fields in the request; each slot 
contains a string bearing tlie value of tlie named field. Listing 1 shows what our 
second GET example above would expand to. 


Listing I, A processed URL frame 


raw ; " /myApp/search. html?field 1 =heilo&field2==worId”, 
data! ” search, html ? f ield l=he llo& field2=wor Id , 
path; "myApp”, 
tag: "search•html", 
form; { 

fieldl: "hello", 
field2: "world" 

} 

) 


Well probably also want to include a _parent slot in the callback specification, so 
that it can inherit from a useful context within the translator (see Listing 2). 

OUR STATE MACHINE 

Like most communications programs, our application can be represented as a state 
machine. The appHcation can be in one of a finite number of states: while in one 
state, the application waits for an event, and the functionality of the program is 
encapsulated in the actions performed during a state change. 

The nHTTPd state machine is shown in Figure I. The arrows between states 
indicate transitions — where the program actually does something. For clarity, my 
implementation of this state machine uses symbols to denote each state, but using 
integer constants would save memory. 
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Lisring 2* The translator callback specification Frame 


parent: self, 

CoinpletionScript := func(inEp, inData, inErr) 
begin 

inEp:Output ("Why did you want " S inData,tag S nil, { 

async! true, 

completionScript: func(inEp, inOpt, inErr) 
begin 

// Do something useful! 

end, 

} 

) t 

inEp:Close()? 
end, 

} 



'concelling 


instantiated 


stopping 


'bound 


"tistening 


servrng 


Figure 1. The nHTTPd server's state machine 

Using a state machine provides many advantages during application development. 
Primarily^ it’s an organizational tool, allowing us to accurately plan and visualize 
what’s going on inside our application. There’s something very soothing (even if 
you’re as bad a mechanic as I am) in imagining an application running as a set of 
gears clanking around, and it’s a lot easier to follow than a spaghetti of method calls. 
There’s also the benefit that most existing protocols are specified and implemented as 
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state machines, which makes porting somebody else’s code a little easier. HTiite the 
Newton is generally a difficult target for porting, porting from a state machine is 
significantly easier than porting from most other kinds of implementation. 

Our state machine is a little odd, because there are really two separate machines 
running at once. We use a protoTCPServer (discussed in detail later) to manage the 
Internet link and provide endpoints listening on port 80 (the standard HTTP server 
port number). This state machine invokes an instance of protoHTTPServer, w^hich 
itself is a smaller state machine that invokes your application. 

GETTING A REQUEST 

nlTTTPd's protoTCPServer deals with all the details of establishing a link, as well as 
instantiating and listening on a TCP socket. The protoTCPServer has two methods: 

• Start requests the link, instantiates an endpoint, and awaits a connection. 

WTien a connection is made, itis accepted, and the callback specTfication’s 
CompIetionScript is called with the resulting endpoint. The callback passed 
to Start is invoked whenever nHTT^Pd receives a connection on the 
monitored port. 

• Stop cancels any open endpoints, discomiects and destroys them, and 
releases the open link. WTien weVe done with the protoTCPServer, we use 
the Stop method to shut dowm all pending connections and close down the 
link. The callback for Stop is called when the teardown is complete and the 
link is released. 

USING THE LINK CONTROLLER 

Looking at the Start method gives a good idea of what's involved in using the Link 
Controller for the average application. The Link Controller APIs are all a.S}Tichronous, 
so as part of the arguments you must provide a context frame and the symbol of the 
completion script to be invoked (we'lJ see the details in a bit). Generally, youll 
perform the following steps: 

L Your application will give the user a chance to configure the link by catling 
InetOpenConnectionSlip. 

2. Your application wUl call InetGrabLink to request a link from the system, 

3. Periodically as the link is established, the callback you provided to 
InetGrabLink will be invoked witli status information. In your callback, 
you'll call InetDisplayStatus to notify the user of the progress of the link 
establishment. 

4. Once the link is established, you'll use NIE endpoints as you would any 
other endpoint. You can also call InetGetLinkStatus to determine the 
current status of the link, to help determine when youVe ready to begin 
using an NIE endpoint, 

5* When you're through with the link, you’ll call InetReieaseLink to end the 
connection. 

The InetOpenConnectionSlip method presents the user with a slip for selecting an 
Internet service provider if no link is currently active. You pass three arguments to 
InetOpenConnectionSlip: the initial ID of the link to be offered (or nil to have the 
system select one for you), the frame to receive the callback message, and the name 
of the slot in the frame that contains the callback method to be invoked. 

Once a selection is made, the callback is invoked with a single argument, either nil 
(indicating that no connection is to be made) or 'connect. If a link is active, the slip 
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is not displayed, the existing link is used, and the callback is immediately invoked with 
the ’connect symbol. Listing 3 shows how we present tlie slip along with a callback 
method to handle the user’s choice (there are several callbacks — one in the listing 
for the user response, one passed to Start to be called in response to an incoming 
connection, and one to be called during link acquisition, as shown later in Listing 4), 


Listing 3* Choosing a connection and hondling the user's choice 

Start := func(iiiCallbackSpec) 
begin 

if fState then return; 
fState 1 = ^choosing; 

InetOpenConnectionSlip(nil, self, ’mConnectSlipCb); 
fCallbackSpecs := Clone(kProtoCallbacks); 
fCallbackSpecs*fStart ;= inCallbackSpec; 
end; 

mConnectSlipCb i- func(inaction) 
begin 

if inAction = 'connect then 
begin 

fState := 'linking; 

fStatusView := fluildContext({_proto: 

GetLayout("protoInetStatusTemplate")}); 
fStatusView:Open(); 

InetGrabLink(nil, self, ’mGrabCb); 

end 

else fState := nil; 


Once the user has selected the preferred link mechanism, a status slip is created and 
presented to the user. The nHlTTd status slip is based on the Newton DTS sample 
Internet status slip, showing only a text view indicating the current status, along with 
a Stop button and a close box. Your status sHp can contain anything you find 
appropriate, as long as it inherits from the protoInetStatusTemplate. Opticmally, 
NIE can create a default status view for your application. 

With the status view built and displayed, call InetGrabLink to request the link 
tliat was indicated by the user. InetGrabLink uses the same arguments as 
IneK3penConnectionSlip, although the callback itself takes three arguments: the 
link ID being used, the current status of the link as an NIE status frame (the only 
slot you need to worry about is the ImkStatus slot), and a result code (which is nil for 
a successfully established link). 

The process of acquiring a link can take a relatively long period of time, since the 
device may have to dial a modem and then execute a chat script to estabh.sh a PPP or 
SLIP stream before being able to conclude successfully To keep your application 
infonned, it invokes a progress callback periodically In your callback, you can use tlie 
function InetDisplayStatus to keep the user apprised of status (see Listing 4). 
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InetDisplayStatus is a versatile function; depending on its arguments, it can do many 
things. You pass the current link ID, a reference to your status view, and a reference 
to the status frame from your callback. In turn, the function will show or hide the 







Listing 4. The InetGrabLink status callback 

mGrabCb ;= fiinc(inLinkID, inStat^ inErr) 
begin 

fLinklD := inLinkID; 
if inErr then 
begin 

:inNotifyError (’’InetGrabLink", inErr); 
fState := nil; 

end 

else 

begin 

I net DisplayStatus(inLinkID, fStatusView, inStat); 

if inStat,linkStatus = 'connected then 

begin 

fState := 'linked; 

InetDisplayStatus{inLinkID, fStatusView, nil); 
fStatusView t- nil; 

;mInstantiateAndBindi); 
end; 
end; 

end 


status dialog or update the status indicatt^r with the text of the current status as 
necessary. Table 1 shows the relarionship between the arguments to InetDisplayStarns 
and the resulting behavior. 


Table 1, InetDisplayStatus arguments and results 


Second orgument 
(view template) 

nil 

Template of a status view 

A currently shown status 
template 


Third orgument 

(status) 

nil 

Status frame (non-nil] 
nil 


Result 

Returns a reference to a default status 
view, and opens the view for you 

Uses the template os the status view 
ond displays the stotus 

Closes and destroys the stotus view 


Note that InctDisplayStatus can even create a status view tor you, if you’re so 
inclined. This status view is built on the protoInetStatusView and provides text 
indications of status to the irsen 

USING ENDPOINTS 

Once the link is established, you’re free to use endpoints to initiate TCP/IP 
connections. Our application uses an array of endpoints to service incoming requests; 
one endpoint is always listening for new connections, while other endpoints may be 
open responding to existing requests. 

Our endpoints begin their life in the method mins tan date And Bind, shown in 
Listing 5, 
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Note that setting up your endpoint works just as you’d expect. In addition, there’s a 
host of compile-time utility functions that aren’t officially supported but theyVe 
useful enough that IVe included them with the program and summarized some of 
them in Table 2. 


Listing 5. Creating and binding on endpoint 

mlnstantiateAndBind := funcf) 
begin 

local myEp; 

if NOT fEndpoints then 
fEndpoints £= []; 
myEp := { 

_proto: protoBasicEndpoint, 

_parent: self, 
fState: nil, 

ExceptionHandler; func{inExp) 
begin 

local luyErr; 

if HasSlot{inExp, *data) then 
myErr inExp,data; 
if myErr <> kCancellationException then 
:Kotify(kNotifyAlert, kAppName, 

"Something bad happened - " & myErr)? 
jmTearDown(self); 
end, 

EventHandler: func{inEvent) 
begin 

if inEvent-eventCode = kCoirnnToolEventDisconnected then 
begin 

:Notify(kNotifyAlert, kAppName, 

''The other side has disconnected,'' & myErr); 

:mTearDown(self); 
end 

else print("Unexpected event (" s inEvent,eventCode & ")")? 
end, 

}? 

AddArraySlot(f Endpoint s, myEp); 
try 

myErr := myEp:Instantiate(myEp, call kGetEndpointConfigOptions 
with (fLinkID, kTCP)}; 
onexception |evt| do 
begin 

:mNotifyError{"Instantiate", 0); 
return? 
end; 

if myErr then 
begin 

:mNotifyError("Instantiate", myErr)? 
return; 
end? 

myEp.fState := 'instantiated; 

fconffnued on next page) 
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Listing 5* Creating and binding an endpoint (continued) 
try 

myErr := inyEp:Bind( 

call kINetBindOptions with (0, fPort), { 
_parent: self, 
async; true, 

Comp1etio nSc ript: mBindCb, 

} 

)t 

onexception |evt| do 
begin 

;mNotifyError("Bind", 0)? 
t mTearDown(myEp); 
return; 
end; 

if myErr then 
begin 

:mNotifyError("Bind", myErr); 

:mTearDown t nyEp); 
return; 
end; 

end 


Table 2. NIE constant functions defined by include files 

Function Arguments 

kNumToHostAddr inAddrArr 

k Host Add rloNum inAddrStr 

kGetEndpointConfIgOptions inLinktO, inProtocoJ 

kINetBindOptions In Loco I Port, InUseDefoultPort 

kTCPConnectOptions I n Remote Add rArr, inRemotePort 

kUDPPutBytesOptions InAddrArr, in Port 


Purpose 

Turns on IP address Info a string in the Form "a,b,c,d" 

Turns a string address In the form "'a.b.c.d" into the 4-byte 
IP address 

Creates an options array for use when an NIE endpoint is 
instantiated 

Creates an options array for use when an NIE endpoint is 
bound 

Creates an options array for use when an NIE TCP endpoint 
is connected 

Creates on options array For use with a UDP endpoint when 
data Is to be sent 


The function kGetEndpomtConfigOptions generates the options array necessary to 
use die NIE endpoint. There are options to request NIE (the met option), specify 
the link kind (the ilid option), and indicate the desired transport (a flag indicating 
TCP or UDP is passed widi the itsv option). 

Wlien binding your endpoint, you’ll have a little more to consider. At the time your 
endpoint is bound, youll pass different options depending on whether your endpoint 
is going to be listening (inbound) or connecting (outbound), and whether the 
endpoint is UDP or TCP. If you’re using a UT)P endpoint, or if your TCP endpoint 
is inbound, youll need to specify a local port number. If your endpoi nt is an 
outbound TCP connection, NIE provides a randomly assigned port number for your 
endpoint. In the event that you need to set an option, you can use the function 
kINetBindOptions, 
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When would you want to specify a port? Most standard Internet applications have 
the notion of a reserved, or well-known, port. The server listens on the well-known 
port and clients specify that port as the destination port. Clients are free to use a 
random port for the source. 

If you're writing intranet applications with dedicated servers, be sure that the 
port numbers you pick do not conflict with welkknown ports. An index of welhknown 
ports is available from Internet RFC (Request for Comments] number 1 700, In general^ 
ports numbered below 1024 ore reserved as well-known ports. * 

The function in Listing 6 creates an ilpt option frame containing the desired local 
port. WeVe invoking Bind asynchronously, and when it’s complete, notification is 
achieved through the invocation of mBindCb. 


Listing 6« Completing a Bind coll 

inBindCb t= func(inEp, inOpt, inBes) 
begin 

if inRes then 
begin 

imTearDown(inEp); 

if inRes <> kCancellationException then 
:mNotifyError(inRes); 

end 

else 

begin 

inEp,fState := 'bound; 
try 

inEp:Listen(nil, { 

_parent: self, 
async; true, 

CompletionScript; mListenCb, 

} 

)? 

onexception |evt| do 
begin 

!mKotifyError("Listen", 0)? 
;in'rearDown(inEpj; 
return; 
end; 
end; 
end; 


From this point, what you do depends on whether you’re expecting an incoming 
conuectitm or initiating an outgoing request. Since Pm doing the former, J call my 
endpoint’s Listen method, which instructs NIE to wait until an incoming request 
occurs. If you were calling Connect on a TCP socket to initiate an outgoing 
connection, this would be where you specify the destination address and port using 
the irts option — you can programmatically generate the appropriate arguments with 
a call to kTCPConnectOptions. In our case, the Newton waits until an incoming 
request is detected, and then notifies the application by calling the completion script 
originally passed to the Listen fiinction (see Listing 7). 
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Listing 7* Processing on incoming request 

mListenCb := funcfinEpp inOpt, inHes) 
begin 

if inRes then 
begin 

:mTearDown(inEp); 

if inRes <> kCancellationException then 
:mNotifyError[inRes ); 

end 

else 

begin 

inEp.fState := ^listening; 
inEp:Accept(nil| { 

_parent: self, 
async: true, 

CompletionScript: niAcceptCb, 

})? 

end? 

end 


The way weVe written it, iiHTTPd is an indiscriminate server — we accept 
connections from anywhere. If you wanted to do access control, or log where 
incoming connections were from, yon could do it before we return control to the 
protoTCPServer’s callback tn inAcceptCb, shown in Listing 8* 

At this point, control is passed to the client of the protoTCPServer, and the request 
phase of the connection has begun. 


Listing 8. Accepting on incoming request 

mAcceptCb := fane{inEp, inOpt, inRes) 
begin 

if kDebugOn then print("mAcceptCb"); 

if inRes then 
begin 

;mTearDown(inEp)? 

if inRes <> kCancellationException then 
:mNotifyError(inRes); 

end 

else 

begin 

inEp.fState ;= 'connected? 
inEp.Close := func{) 
begin 

if kDebugOn then print("Close”); 

;mTearDown(inEp)? 
end? 

fGallbackSpecs.fStart:7CompletionScript(inEp, nil, nil); 
end; 

end 
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That’s the basics of the application — creating endpoints, accepting configuration 
from the user, waiting for requests, and accepting remote connections. We still need 
to read serial data to process URLs, do something useful with them, and write out 
response data. But first, let’s do some more work with the DNS. 

USING THE DOMAIN NAME SERVICE 

For nHTTPd to be truly useful, it needs to track and log the host names generating 
incoming requests. We could simply log the IP addresses of incoming hosts, but these 
would mean Uttle to the user. Instead, nHTTPd uses the DNS of NIE to ascertain 
the host name of incoming queries. 

The DNS, like the Link Controller, uses asynchronous calls to do its work. You’ll 
pass information to one of the DNS functions and receive a response through a 
completion script. The DNS provides several global functions for your use: 

• DNSGetAddressFromName, which converts a host name string to its IP 
equivalent 

• DNSGetMailAddressFromName, which discovers the TP address for a mail 
server given a host name in a particular domain 

• DNSGetMailServerFromName, which returns the name of the mail server 
given a host name 

• DNSGetNameFromAddress, which returns a host name string given the FP 
address 

• DNSCancelRequests, which cancels all requests associated with a specific 
context 

The first four functions take three arguments: the key for the data to be retrieved, the 
client context, and a symbol denoting the callback. The cancellation function takes 
only a client context and a callback symbol. For all hut the last function, the callback 
receives a results array and result code. The results array contains result frames, each 
with one or more of the foil ova ng slots: 

• type, the result type (kDNSAddressType or kDNSDomainType) 

• resuitDomainName, a string containing the resulting domain name 

• resuItlPAddress, an array containing die 4-byte IP address 

Listing 9 shows a code fragment that determines the host name for a particular IP 
address and logs it to a soup. 

RECEIVING INPUT 

Now that we have a connection and have logged the domain it came from, we need 
to do the work of reading the LFRL request. Getting data into an application is done 
as with any other endpoint: set up an input specification and wait for your data to 
come to you- The input specification used by nHTTPd is simple, as show^n in 
Listing 10. 

If youVe done Newton communications work before, this is nothing new^. If you 
haven’t, it’s worth taking a moment to consider the notion of an input specification. 

Rather than providing a traditional stream for input, the Newton OS provides the 
notion of an input specification, which describes the format of the infonnation your 
application expects. You build an input specification (or “input spec” for short) using 
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Listing 9. Tronslating a name \q an address and logging it 

DNSGetAddressFroniName( fDestAddr, self, 'mDHSResultCb); 

^U}^^SResultCb := func(inResultArr, inKesultCode) 
begin 

if inResultCode then 
begin 

// Rats, It failed, 

print(*^DNS lookup failed because of " &£< inResultCode); 

end 

else 

begin 

local myAddrFrame; 

local myHandyAddresses := foreach myAddrFrame in inResultArr 

collect myAddrFrame,resultDomainName; 
fLogSoup:AddToDefaultStoreXmit( { 
hostnames: myHandyAddresses, 
request: fRequeststring 

} r 

kAppSymbol); 

end; 

end; 


Listing T 0* The input specification 

local myInputSpec := { 
form: 'string, 

termination: { endSequence; unicodeCR }, 
filter; { 

byteproxy: [ 

{ byte: kUnicodeBS, proxy: nil 
{ byte; kUnicodeLF, proxy; nil }, 

] 

}i 

inputScript: func{inEp, inData, inTerm, inOpt) 
begin 

local myResult, myClient; 

// Optimization - why bother if nobody's registered? 
if Length(fRegistry) = 0 then 
!mReportBogusAndClose(myEp); 

if StrLen(inData) = 0 then return; 

// Change stuff like %20 to ’ ’* 

:mFilterPercentEscapes(inData); 

// Break out the data frame for the application callback* 
myResult := : mCreateArguinents( inData); 
foreach myClient in fRegistry do 

if StrEqual(myClient,path, myResult,path) then 
break; 

(continued on next page) 
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Lisring 10. The Input specification (continued) 

if I^OT Sir Equal (my Client, path, myRe suit, path) then 
:mReportBogusAiidClose (niyEp); 
else 

inyClient.callback:Ccnnpletio0Script(inServer, myResult, nil); 

end, 

completionScript: func(inEp, inOpt, inRes) 
begin 

if inRes <> kCancellationException then 
begin 

print{”Input spec saw error ” & inRes); 

:mTearDown(myEp); 
end; 
end, 

}; 

myEp;SetlnputSpec(myInputSpec); 


things like the class of die incoming data, its length or an array of possible termination 
characters, how long to wait for input, or communications flags that denote the end 
of input. The Newton uses the input spec to watch for input in the background while 
your application is running. Once the conditions of the input spec are met, its 
inputScript is invoked; if the input spec is never satisfied, the CompletionScript may 
be invoked to notify you that the input spec was never filled. This will happen if you 
timeout on a receive, or if the endpoint is closed while youVe expecting input. As 
your application runs, it can change which input spec is active with the endpoint 
method SetInputSpec. 'This aspect of tiie Newton commimications model makes 
writing applications based on state machines incredibly easy, and porting most code 
from stream-based environments painfully difficult. For more on communications 
state machines, see "“'Use a State xMachine.” 

There’s an exception to input handling that you should know about, even if you never 
use it. Wtiien you use a TCP endpoint, expedited data isn’t passed to your application 
through the nonnal input spec means. Instead, any exjiedited data is sent as an event 
to your endpoint’s event handler. Listing 11 show^s such an event handler (the method 
mTearDowm, called in this event handler and many other places, is shown later). 


USE A STATE MACHINE 

When planning an application, take pains to be sure you've developed a good state 
machine to represent it Effort during the design phase will be repaid □ thousandfold 
when your application's communications code is almost entirely on array of input 
specifications and their scripts. If you're new to working with stote machines and 
communications^ check out the Newton DTS sample CommsFSM, which has enough 
to get you started. 

If you're porting code, take heart, and do the same. Virtually all protocols can be 
well represented by a state machine, and if you do so you'll find it's eosier to 
implement. At all costs avoid simulating a UNIX®-style stream with an endpoint — 
it's expensive, and you'll almost never need the functionality of a byte stream. 
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Listing 11, Receiving expedited data In an event handler 

EventKandler;func(inEvent) 
begin 

if inEvent.eventCode = kCoimToolEventDisconnected then 
begin 

GetRoot {) t Notif y (ktlotif yAlert, kAppKame ^ 

"The other side has disconnected.")? 

:mTearDown(self); 

end 

else if inEvent.eventGode^kEventToolSpecific then 
if inEvent.data < 0 then 

print(^Got an error (" & inEvent.data & ")"); 
else 

print("Expedited datal The byte was" s inEvent.data); 

else 

print("Unexpected event (" s inEvent.eventCode & 


WRITING A RESPONSE 

By Jiow, I hope that youVe gxiessecl how to send data: you use the endpoint^s Output 
method, showTi in Listing 12. 


Listing 12. Sending data 

inEp:Output("Why did you want " & inData.tag & nil, { 

async: true, 

completionScript; func(inEp, inOpti inErr) 
begin 

//Do something useful! 
end, 

}); 


NIE provides two options of interest for output. The first is the expedited data option, 
which can be used to set the expedited flag on a TCP packet. Expedited data is c)ften 
used, for example, to signal the other end of the connection that it should cease 
transmitting data immediately. An expedited data byte is denoted with the iexp option, 
with a frame like the one shown in Listing 13 (where iuByte is the byte to be expedited). 

TTie other option is required for UDP communications — the address and port of 
the destination. This is required when output operations are performed, because 
UDP is connectionless (and you didn't specify the remote address during the call to 
your endpoint’s Connect method). More on that in a bit. 

DISCONNECTING WHEN DONE 

Tearing down and cleaning up is exactly the same as witli a standard endpoint: cancel 
any pending operations, disconnect, unbind, and then dispose of your endpoint. The 
protoTCPServer uses the method inTearDown, in conjunction with an endpoint’s 
state variable fState, to determine the appropriate behavior (see Listing 14), 
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Listing 13. An expedlfed data Frame 
{ 

label: "iexp"f 
type: 'option, 
opcode: opSetRequired, 
result: nil, 
form: 'template, 
data: { 

argList: f inByte ], 
typeList: ['struct, 'byte ], 

}r 


Listing 14. Disconnect and cleanup 

mTearDown := func(inEp) 
begin 

if inEp-fState = nil then 
print("We do nothing ,"); 
else if inEp,fState = 'Instantiated then 
:mUnBindCb(inEp, inOpt, inE rr )t 
else if inEp,fState = ‘bound then 

:mDisconnectCb(inEp, inOpt, inErr); 
else if inEp,fState “ 'listening then 
begin 

inEp:Cancel({ 

parent; self, 

async: false, // avoid async race condition 
completionScript: func(inEp, inOpt, inErr) 
:mDlsconiiectCb(iitEp, inOpt, inErr) 

>); 

end 

else if inEp,fState = 'connected then 
inEp;inDisconnect(); 

else if kDebugOn then print("Endpoint is already closingl"); 

end 

mDisconnectCb := tunc(inEp, inOpt, inRes) 
begin 
try 

inEp;Unbind ({ 

_parent: self, 
async: true, 

completionScript; func(inEp, inOpt, inRes) 
begin 

:niUnbindCb(inEp, inOpt, inRes); 
end; 

} 

) r 

onexception |evt| do nil; 
end; 

/* and the other callbacks look similar,,,*/ 







There’s not much to discuss about the teardown procedure, except a couple of hard 
knocks you may get M^hen acaially using NIE endpoints (or any other kind); 

* It^s much better fonn to track your cndpciint’s state using a separate value 
than to retrieve it with die endpoint’s State method, so that the application 
can use the state in other areas such as user interface or as part of the overall 
state machine* 

• Be sure you wrap the endpoint’s teardown methods in exception handlers. 
Although notliing’s supposed to go wrong during an endpoint’s teardown and 
cleanup, you never know, and you don't want an application throwing 
exceptions to your end users* This is especially true if your endpoint is being 
tom down after something bad has already happened to an open connection. 

Unlike other endpoints, once you’ve disposed of an NIE endpoint, there’s still a link 
hanging around that you’ll need to get rid of* You do this with a call to the Link 
Controller’s InetReleaseLink function, which will drop the link only if no other 
application is currently using it. Our protoTCPServer invokes this method after 
disposing of its last endpoint, as shown in Listing 15. 

InetReleaseLink takes the same arguments as InetGrabLink —^ the link ID, a 
reference to a status view if appre^priate, and what to put into the status view (or nil to 
conceal it entirely). Although it’s obvious, be sure your application has the same 
number of TnctGrahLink calls and InetReleaseLink calls. It’s embarrassing to leave 
the link open or clobber it on another application. 


Listing 15. Disposing of endpoints and releasing the link 

mUnbindCb := func(inEp, inOpt, inErr) 
begin 
try 

itiEp: Dispose () j 
onexception |evt| do tiilj 
S et Remove(fE ndpoint s, inEp); 

if Length(fEndpoints) = 0 then :mReleasGLink(); 
end; 

[tiReleaseLink := func{) 
begin 

fState := 'stopping; 

InetHeleaseLink;{fLinkID, self, ’mReleaseCb); 

end 

mEeleaseCB := func(inLinkID, inStat, inErr) 
begin 

if inErr then 
begin 

: loNotifyError (“ 1 netReleaseLink", inErr); 
fState 1 = nil; 
fEndpoints i= nil; 

fCallbackSpecs.fStop:?CompletionScript[self, nil, inErr); 
fCallbackSpecs t= nil; 

end 

(continued on next poge) 
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Listing 15, Disposing of endpoints and releasing the link (continued) 

else 

begin 

if inStat.IinkStatns = 'idle then 
begin 

InetDisplayStatus {inLinJcID, fStatusView, nil J; 
fState := nil? 
fEndpoints ;= nil; 

fCallbackSpecs,fStop:7CompletionScript(nil, nil, nil); 
end; 
end; 

end 


In addition to releasing the link when you’re done with it, you’ll want to release it if 
you won’t be using it for a long period of time (over 1 5 minutes or so) to avoid 
battery drain from an internal modem or the like. 

WHAT IF THIS WERE UDP? 

The Newton endpoint model is connection-oriented; it doesn’t directly w ork with a 
connectionless protocol such as UDR Invocation of a UDP endpoint is essentially 
similar to a TCP endpoint, except that you never indicate the destination IP and port 
at the time you connect Instead, you’ll indicate them during your call to the 
endpoints Outjiut method, using the iuds option. 

WTen performing input or output with UDP, be sure you always indicate packet 
lioimdaries. You do this by forcing a packet boundary on output, by including the 
kPacket and kEOP flags in your output and input specifications {see Listing 16). 

'Table 3 indicates which options you’ll set at which times for which kinds of connections. 
You can use this as a summary to help you in creating your own applications. 


Listing 16* Using packet boundaries for UDP 

local myInputspec ;= { 
form; 'string, 

termination: {useEOP: true), 
rcvFlags; kPacketi 
revOptions: { 
label: "'iuss", 
type; ‘option, 
opcode! opGet Cur r e nt, 
result: nil, 
form; 'template, 
data; { 

arglist: [ 

[ 0,0,0,0 ], // Host address 

0, // Host port 

L 

(continued on next page) 
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Listing 16. Using packet boundaries For UDP (continued) 

typelist; [ 

['array, 'byte, 4], 

'street, 

Ir 

}. 

inputScript: func(inEp, inData, inTerm, inOpt) 
begin 

//Do something with the data* 
end, 

compietionScripti func(inEp, inOpt, inRes) 
begin 

if inRes <> kCancellationException then 
begin 

print("Input spec saw error " £ inRes); 

:mTearDown(inEp); 
end; 
end, 

}? 

fEndpoint:SetInputSpec(myInputSpec); 
fEndpoint:Output("Hello worldi", 

call kDDPPutBytesOptions with {fAddr, fPort), { 
async: true, 

sendFlags: kPacket+kEOP, 

completionScriptI funciinEp, inOpt, inErr) 

begin 

// Do something useful i 
end, 

>); 


Table 3. NIE options and their uses 


Option 

Provided by 

Used 

v^ith 

Inbound/ 

outbound 

Purpose 

inet 

kGefEn d poi n tC o nf 1 g OpH on s 

Both 

Both 

Specify NIE ot mstantiote 

ilid 

kGefEndpointConfigOpHons 

Both 

Both 

Specify link ID at instantiate 

ifsv 

kGetE n d poi n tConf j g O phi ons 

Both 

Both 

Specify either TCP or UDP at instonhale 

ilpt 

kINetBindOpHons 

TCP 

Inbound 

Specify local port for inbound TCP during bind 

ilpt 

klNetBindOptfons 

UDP 

Both 

Specify local port for UDP during bind 

irts 

kTC PCon necKD pfion s 

TCP 

Outbound 

Specify remote IP and port for TCP during connect 

iexp 

N/A 

TCP 

Both 

Specify to expedite data during output 

iuss 

kU DP P ulfiy teOpt 1 ons 

UDP 

Both 

Specify remote host and port during UDP output 


GO OUT THERE AND NEWTONIZE THE INTERNET! 

With the exception of link-level management, using NIE is the same as using any 
other kind of Newton endpoint. The NIE’s Link Controller and DNS use new global 
functions to provide support for a unified link-level interface and domain name 
service. The design of NIE strongly encourages asynchronous programming 
techniques. 
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Using NIE to port existing applications is easy, as is writing new ones. With a little 
work, your application can soon be merging on the infobahn among the desktop 
machines already cruising the Net 


RELATED READING 

• '^ATSIat: A Shared Whiteboard for Newton" by Ray Rischpater, PDA Developers, 
July 1996. 

• TCP/IP Iffuskoted (3 volumes) by W. Richard Stevens (AddisonWes ley 1994-95), 

• Newton Programmer s Guide for Newton 2.0 by Apple Computer, inc. [Addison- 
Wesley 1996), Chapter 24, "Built-in Communications Tools." 

• Newfon /nfemet Enob/er (Apple Computer, Ir^c,, 1996). This is provided on the 
Newton Developer CD as the NIE API Guide and con also be found on the Web 
at http://v/ww,devworld.apple.com/dev/newton/tools/nie.htmL 
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Newton 


Don’t be left 


in the dark. 


Get the /otest Newton development information from Apple. 

Check out the Newton Development Web site 
http://www.devworld.apple.com/dev/newtondev.shtml 
for Newton development resources such as 

• sample code 

• Q&A’s 

• documentation 

• self-paced training 

• development tools, including Newton Internet Enabler (NIE) 

Coming soon: NIE I. i with support for PAP and CHAP authorization 

'^’Newton 
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Newton 
Q&A: 
Ask the 
Llama 


Q 


/ recently saw the amiouncefnmt of two new Newton devices —the MessagePad 2000 
and the eMate 300 — and / have a few (luestions. First, will my application run fine? 


If your application was written correctly for Newton OS 2.0, for the most part it 
will work fine on Newton OS 2.1, which is what the new devices use. ^‘Correctly** 
here means that you call only documented functions, including platform file 
functions where appropriate* It also means that your application works with 
different screen sizes by using GetAppParams in combination with minimLiin 
and maximum sizes* 


Q 


What are the most imponant thin^ to check in my application to ensure that ifs 
completely mmpatible with the new devices? 


A 


There are four broad areas to check: speed, screen size, views, and PC cards. 


Speed. The new units are faster than the current ones* In the case of the 
MessagePad 2000, the difference is quite large* Unfortunately, it^s possible for 
some things to be too fast* The new OS takes care of several speed issues for 
you — scrolling, for example -— hut there are still some areas you should check. 


Check those places where you’re doing repeated actions from a viewClickScript* 
A t)'pical usage would be a button that will continualJy perform an action as 
long as the user presses it. If you use a loop in a viewClickScript to do the 
repetition, you may find that there are too many repetitions or that the 
repetitive action occurs too quickly. I ’he same problem can occur if you don’t 
use the scrolling API provided by the system, as scrolling is one area that has 
deliberately been slow^ed down on die MessagePad 2000* 


Loops can also cause problems when theyVe used for timing. In general, you 
shouldn’t use loops for this purpose; use Ticks instead* If you must use a loop, 
set the counter for that loop based on a known reference like Ticks or 
TimelnSeconds. 


Operations that used to be long enough to require user feedback may now 
happen fast enough that no feedback is required* This can happen in two places: 

* You may have been deliberately nirning on the busy box* The result can be 
a busy box that flashes very brie fly, which can be distracting. 

• You may have implemented progress bars using DoProgress, protoStatiis, 
or even a protoGauge* Try removing the progress indicator and checking 
whether the operation is now fast enough. Note that most of the progress 
indicators take time to draw and update —- in some cases significantly longer 
than the time to do the operation for which the progress is being displayed* 

Screen size. Be sure your application works properly in both portrait and 
landscape orientation, with the button bar on both the left and the right* In 
addition to the size cif your overall application on the screen, check areas where 
you use complex justification or dynamic allocation of view children* Check that 
the children are correctly aligned — and that there are the correct number of 
children. 


The llpma is Jhe unofficial mascot of the 
Developer Technical Support group in Apple's 
Newton Systems Group. Send your Newton- 


related questions to dr.llama@newton.applexom. 
The first time we use □ question from you, well 
send you □ T-shirt,* 
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Also, be sure your borders don\ go outside the application area. Note that 
borders are drawn outside the view. Y<ju can find your global bounds with the 
borders by calling GlobalOuterBox. 

Views. The most likely problem related to views is assuming that the top left of 
the application area is always at (0, 0) in global coordinates. This is no longer 
the case since the button bar, which is 46 pixels wade, can be on the left side of 
the screen. A typical place for this problem to occur is in a viewCdickScript 
where you do something with a point that^s actually 46 pixels out fi-om where 
you expect it to be. Rotate to landscape orientation and put the button bar on 
the left; then try tapping on the right side of your application. One sure way to 
cause problems is to forget to send SyncView to your base application riew after 
a ReorientToScreen message has been sent. 

Another possible view problem is diat any view can be the keyATew. Don’t 
assume that the keyView can accept text input; in particularj don’t use calls like 
SetValue to jam the text slot (which may not be there). You may w'ant to check 
the class of the key View. 

PC cards. You should check that your application works when two PC card 
slots are being used for storage. Search for the following pieces of had code: 

GetStorea () [ 1 ]; // BAD — 0 is the only number documented to work 

Length{GetStoresO); // doesn't tell you the number of PC cards 

If you have code like dhs, you’ll have to change it The first case —^ assuming 
there’s a store at the second position in the array — is not a good idea. Even if 
there’s a store at that position, it may not be the same store that was there the 
last time yon checked. Also note that the positions in the array do not correspond 
to physical PC card slot positions. The second case can fail for similar reasons. 
That is, checking the length of the array returned by GetStores doesn’t tell you 
how many PC cards are currently installed. 

Abmg the same lines, if youVe still using the action (routing) picker to move 
items t(] die card, you should change to using the filing interface. ^\lso, make 
sure that you use the FileThis method to move items to different stores, and 
that you look at the arguments provided by FileTbis; some application code 
seems to assume that there are only twt] stores. For adding soup entries, 
remember to call AddToDefaulStorcXmit instead of using the store direedy. 

You might also encounter a problem with endpoints that could use PC card 
modems, lo setup your modem endpoint, call MakeModemOption, which will 
construct the correct options baseti on the user modem preferences and available 
I^C card modems. 


Q 

A 


Are there any features that are important to suppoft in the new devices? 

The most important thing is to make sure your application works. After diat, 
there are some important updates you can make to support features in the new 
devices. 
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First, make sure your application can be dragged, assuming of course that it’s 
not fnll-screen in all orientations. You can do this by changing your base view to 
a protoDragger with either some sort of status bar (preferably newtStanisBar) or 





a proroLargeCloseBox. Remember to make sure the borders of the protoDragger 
will be contained in the application area; you can use GlobalOuterBox to check 
this. And while yoif re at it, you can check that your applicadon will handle any 
screen size. 

You may also want to see whether you can improve your use of screen space. 
Note that your major layouts (for example, detail and overview) don't have to be 
the same size. The Names application is a good example of this. 

Another important feature to support is the use of the keyboard. Add the 
required keyboard commands to your application. As of this writing you can 
find this information in the “User Interface Guidelines for Newton OS 2.1 
Keyboard Enhancements” document. If your application is based on NewtApp, 
most of this work is done for you; otherwise you’ll have to add almost all the 
keyboard conunands yourself. Once ytiuVe supported the required set, add 
other ccmmands tliat make sense for your application. Don’t forget keyboard 
navigation in your overview. 

A related feature that’s good to support on both Newton OS 2.0 and 2.1 devices is 
condirional display of embedded keyboards. You can use the Keyboard Connected 
global function to check whether a keyboard is connected; if it is, don’t display 
embedded keyboards unless they’re highly specialized. 

If you Ve using the infrared (IR) communications tool, you should use IrDA if 
possible. This will give you a faster transfer rate and a much more robust 
protocol. If your application might be communicating with older units, be sure 
to give your users a choice of IR connection types, since older units can only use 
die ASK protocol. Newton OS 2.1 sdll supports all the IR options from 2.0, 
Note that using the action menu to beam infonnation will do the right thing. 

You should also take advantage of the grayscale feature, by using tlie new RGB- 
based gray shades (that is, kRGB_Grayl through 15) instead of the dithered 
gray patterns. Dithered patterns are usually specified as vfGray, vfLightGray, 
and so on. You can also change your owm patterns to use grayscale. Although 
the dithered patterns still work, the true gray RGB shades look a lot better. 
You’Ll want to wrap the specification in a check to make sure that grayscale is 
available. Naturally you’ll want to update important parts of your application to 
use grayscale — for example, your splash screen and Extras icon. 

Finally, if you’re targetiiig the eMate and the education market, you should 
update your application for mulriuser mode. This could be an extensive change, 
since you’ll have to modify your interface and the names of all soups that you 
save. 


Thcinks to jXopher Bell, Bob Ebep Davjd Fedor, If you need more answers, toke o look ot 

Ryan Robertson, Jim Schrom, Maurice Sharp, and the Newton developer Web page, at http:// 

Bruce Thompson for these onswers.^ www. devworld.apple.com/dev/newtondev.shtml * 
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THE VETERAN 
NEOPHYTE 

Digital Karma 


JOE WILLIAMS 


So dunes a good deed in a wemj ivorld. 

— Willy Wonka 

We all shine on. 

—Jolin Lennon, Instant Karnui 

We at Delta Tao Software (ereators of Spaceward Jlo!, 
Strategic Conquest, and Ericas Ultimate Solitaire) lia%^e 
been working on Clan Lord, a network game that may 
someday have thousands of [ilayers ex[)l(3ring and 
colonizing an tdectronie landscape* We want a 
harmonitnis online world thars enjtjyable for every 
player, and w^eVe come up with a system that encourages 
this, w iihoui authoritarian overtones — or at least we 
hope it wilL d'his column looks over some of our system's 
ineclianics, repercussions, and possible applications 
beyond gaming, and gives some food for thought for 
your own projt^cts* 

HOW CLAN LORD USES KARMA 

Clan Lord is a big Mac network game. (No, not a 
Big Mac network game; we\l hate getting sued by 
,'VlcDrjnakrs!) Network games are nodiiug new to us, 
but now, with the massive proliferation of die Internet, 
we want to do a tmly epic game. 

Clan T.ortl doesn’t fall under the traditional definition 
of a game: there’s no end, and there are no w'ioners and 
losers. It’s more like a complete world, and each player 
is a member of an online society. Online societies 
naturally develop their own customs, ethics, and morals, 
just as other groups do. Our goal is to have the world 
be enjoyable — a pleasant place to meet and interact 

'The key to a good party is inviting die right people. 
Some people enhance tlieir environment. In an online 


world, they answer questions, help people, and 
encourage others to exhibit proper behavior. We’ll call 
these people “good.” 

Some people do their best to ruin the part)" for everyone. 
In an online world, they ridicule, shout, and abuse. 
They’re often found saying things like “Boh Dole is a 
lemonhead!” and “HOWARD STURN RULEZ!” 
We’ll call these people “bad.’^ 

On a service like America Online, the worst people are 
eventually ejected. But good people generally receive 
only personal satisfaction from their sonietinies 
considerable efforts. That the Internet information- 
sharing exchange works so well is a marvel that speaks 
w'ell of (oft-ridiculed) human nature, hut it could work 
even better. Our goal is to increase the ratio of good 
people to bad and the likelihood of good heliavior. 

Without external controls, games like this (usually called 
MUDs, for Multi-User Dungeons) tend to devolve into 
hack-and-slash slugfests. New^ players join in, only to 
hnd themselves repeatedly killed by more experienced 
players. Discouraged and humiliated, they abandon the 
game, d'his problem is usually “hxed” by rule changes 
that make it impossible to attack Jiew^er [dayers, or by 
threats from the game developers to eject (bad) people 
who hunt other players, lliese soluiions often cause as 
many problems as they solve. Rsiahlished games are 
most succcssftil when there’s a core of (gootl) veterans 
who encourage and protect die “newbies.” 

So w'e w ant lots of good people, and not too many bad 
ones — hut hf>w do you tell one from the other? A host 
could moderate, llagging people one w^ay f)r the other. 
But this is SLilijective, and it reeks of authoritarianism. 
It’s also too much like work. We came tip whh a painless, 
automatic solution for our game: digital karma. 

for every day you spend in Clan Lord, you can give 
100 karma points to other players, as either good karma 
or bad karma. IF someone solves a problem for you, or 
says something you agree witli, or even gives a friendly 
waird to a stranger, you can send them .some good karma. 
If someone insults, curses, lies, or bugs you in any way, 
you can send diem some bad karma. You can’t give 
karma to yourself, and you can’t change (or respend) 
the kanna other people give you. 

Over time, this karma adds up to a number telling how' 
“good” a person is. People with good karma earned it 
witli good words and deeds, and people with bad karma 
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earned it by lieing annoying and antisncial. In Clan Lord, 
some places are accessible only to people with good 
karma, while people with had karma may have to fight 
their way out of “Hell” w'hen they die. Organizations of 
players (called ckm, of course) also have karma ratings^ 
just by summing the karma of their members, 

BUT DOES IT WORK? 

There’s never been a digital karma system, so we spent 
a lot of time worrying that it might cause as many or 
more problems than it solves. WTiat if bad people abuse 
tlie system to make themselves appear good? VVTiat if 
good people go unrewarded, become disillusioned, and 
go bad or — worse — quit altogether? 

It might be that, since the totaJ sum of karma is large, 
individual abuses would get averaged out. Since each 
person gets 100 karma points to distribute per day, 
thousands of people means hundreds of thousands of 
karma points moving around. However, since the 
average karma received by each person is 100 a day, an 
indi\ddual can concentrate his or her karma to have a 
substantial influence on specific other individuals. 

For example, Ma and Pa Barker spend a day tormenting 
Elvis. (See Figure 1.) Elvis gives each of them 50 bad 
karma. But Ma gives Pa 80 good karma for holding Elvis 
down while she kicks him. And Pa gives Ma 80 good 
karma for doing such a good job tying Elvis’s hands to 
his ankles. And they each give Elvis 20 bad kanna for 
whining so much. MTieri lovely Rita (Meter Maid) comes 
by, she might cart Elvis (with 40 bad karma) off to jail 
for tonnenting the obviously virtuous Barkers (with 30 
good kanna each). “You must have really made them 
angry,” she murmurs as she slips on the handcuffs. 





-40 total 

Figure 1. Karma distnbution 


This sort of thing is certain to happen, bur it’s likely 
that in the long run the Barkers’ evil ways wnll catch up 
with them, Elvis can relate the tale to his friends George, 
John, Paul, and Ringo, who together can inflict more 
bad kanna on those nasty Barkers than they know what 
to do with, Wiat’s more, the Barkers have gone on to 
annoy yet another innocent bandsman who can inflict 
some l)ad kanna of his own. In the long run, the Barkers 
have to spend as much time pleasing people (even each 
other) as hurting them to keep their karma in the black. 

MTiat about the problem of do-gooders not getting 
rew^arded? Johnny B, wanders in to find helpless Elvis, 
tied up and bruised from his run-in with the Barkers. 

He cuts away the bonds, applies first aid, and gives 
Elvis some spending money* Elvis, instead of bestowing 
good karma on Johnny B., inflicts bad karma on the 
Barkers. Johnny B. finds himself with no better karma, 
despite his afternoon of good deeds. Maybe next time 
he’ll be less inclined to help the helpless. 

But probably not. He still gets all the intangible karma 
he wT)uJd have gotten before our system was in place. 
Elvis is still grateful. Johnny B. will, over time, get plenty 
of good karma for his benevolent activities. In addition 
to getting the unquanofiable benefits that come with 
doing a good turn daily, he’ll get an occasional reward 
of good karma. He’ll probably be even more likely to 
do good deeds than he was before. 

Now, the worst case, Ozzy, after watching Born 

Killers^ decides it would be fiin to see just how much 
bad kanna he can rack up. He traipses through the 
countryside setting fire to outliouses, pushing 
grandmothers down stairs, and biting the heads off of 
innocent rodents. He’s bad to the bc^ne. He racks so 
much bad karma that he grows horns and hooves. But 
he doesn’t care — he’s going for the record. The 
baddest cat ever, and our htde system gives him the 
numbers to prove it. Aren’t we just egging him on? 

There are always going to be a select few who delight 
in infamy. Perhaps a few of those could be persuaded to 
form vigilante grcjups, hunting the Most Wanted of the 
Bad Karma Boys, just as many folks are going to go for 
the evil-punishing record as for the bad karraa record. 
We’d turn those of Ozzy’s frame of mind against each 
other. His worst enemy is his own kind. 

WHERE DOES IT GO FROM THERE? 

Besides modifying behavior, kanna studies can identify 
trends, and possibly give w^amings of societal problems. 
The ratio of good karma to bad kanna is an indicator of 
how happy the society is as a w'hole. A sudden drop in 
that ratic> could be an early symptom that something is 
wrong, giving us a chance to nip the pn^blem in the 
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hud. If we do our job, that ratio should see a gradual 
[ucrease over time, as we weed out things that make 
people unhappy. 

We'll no doubt also see some interesting statistics. I'm 
curious to see whether people who send lots of bad 
karma are the same people who receive it, and vice 
versa, IVe certainly always suspected that tliat's how it 
works in life. Any complex economic system, like our 
described karma system, is largely unpredictable, V\Tio's 
to say what kind of karma wars might erupt? A system 
like this will have consequences nobody anticipates. It's 
fun to do thought experiments, as weVe done here, but 
the fact is we won’t really know until afterward, 

jVnd there are lots of questions tor which we hesitate 
to guess die answers: Is it! letter to give karma feedback 
to recipients immediately, so as to hel[i them modify 
their actions appropriately? Or is it smarter to delay 
this information and make it anonymous, so that 
repercussions and threats won't influence its delivery? 
Who knows? These questions aren’t likely to be 
answered without lots of testing and experimentation, 
hut once that's done, we're likely to have a more 
pleasant aiul predictahle online society. 

We’ve lieen talking alxiui digital karma in terms of 
our game, luit that doesn’t need to be where it ends. 
Newsgroups and hulletin hoards w^ould eertainly benefit 
by having more good peo[)lc and fewer l)ad. You could 
screen out had-karma messages nr the people that post 
them. y\nd people who post w^ould get mevisurahle 
feedback on how' helpful their posts are, w ithout having 
to sift through a lot of noise. 

INSTANT KARMA'S GONNA GET YOU 

Predicting how computers will be used has never been 
easy. In ilic fifties, people thought computers w^ould 
eventually calculate missile trajectories and save die 
world from the evil comnumists. In the seventies, the 
atlvent of the personal computer led Marketing people 
to revea! the true possibilities: we could balance our 
checkbooks and organize our recipes. 

In fact, technology has affected nearly every^ aspect of 
our lives — or my life, anyway. But technology hasn’t 
had much effect on social behavior, w^hich is probably 
the one area where we need it most. With the possible 
exceptions of soothing fish tank screen-savers and 
“simulations” tiiat show the perils of evildoing by 


exploding the spleens of on dead Nazis, computers have 
made even less impact on social mores than Dungeons 
and Dragons, 

Not every piece of software, and certainly not every 
game, can (or should) try to have social relevance. But 
it's sure fun to keep one's eyes open for the possibility. 
That’s how the Mac was created in the first place: 
computer geeks trying to change the world. 

Naturally, kanna already exists outside the online world 
— it’s just intangible and unquantifiable. Do-gooders 
(dam them!) tend to get what's coming to themj Fin 
more likely to go out of my way to help someone who 
has been helpful to others in the past. But it would sure 
be nice to be able to quantify this karma, so that we 
could get an idea of someone's “goodness” upon first 
meeting. Of course, it's possible that trying to quantify 
karma like this, putting numbers to it, wall just create a 
sort of “behavioral economy,” whereas the “real” karma, 
the intangible kind, w^ill continue to exist independently, 
however we keep score. 

Wouldn't it be nice to be able to distribute karma in the 
real w'orld? If we tracked it properly, karma would be 
more important than credit — as it should be. Someday, 
with technology’s help, we might be able to point a 
remtjte control and push a couple of l)Littons to reward 
that nice librarian or those kids that wTote that great 
game, < )r finally do something alxuit that granny in her 
fume-spewing Pinto, that dog-kicking punk, or the 
neighbor who mows hi>s lawn at five-thirty in the 
morning. 

Indeed, digital karma could revolutionize society — or 
maybe it's just a thought experiment alxnir a potential 
feariire of a funire game that might not even ship. 


RECOMMENDED READING 

• The Too of Pooh by Benjamin Hoff (E. P. DutJon, 
1982). 

• Ain't Nobody's Business ff You Do by Peter 
McWilliams (Prelude Press, I 993). 

• Caivin and Hobbes by Bill WaUerson [Andrews 
□ndMcMeef 1987), 
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Macintosh 

Q&A 


Q / notked in QuickTime 2.5 that there are new selectors in the Movie Impott API 
that arenk described in Inside Macintosh: QuickTime Compontmts. Alt bough I found 
some infofymition in Tecbnote QT04, ""QuickTime L6.1 Features,^^ I haven^t bee?t 
able to locate any in formation about the kMovielmportGetFileTypeSelect and 
kMovieImpof-t Data Ref Select selectors. Can you tell me something about these i 

A The kMovielmportGetFiteTypeSelect and kMovielmportDataRefSelect 
selectors were added to support some features that were under iuvestigation 
with the QidckTime for Netscape plugdn, Wliile these selectors are supported 
by some of the Apple movie data import components, they don’t provide any 
new functionality and there’s no reason to consider implementing them in your 
movie data import component at this time. 


Q 


My application plays four QuickTime movies simultaneomly fi‘om a Director project. 
Each of the movies has a single music track with no other video or sound tracks, and two 
of the movies me more than one imtrumenL The Director project allows the user to 
control the volume level of each movie mdependently. The application works great on 
the Macmtosh with QuickTime 2.f tut under Windows with QuickTime 2A.2 only 
one musk track plays at a time. Is it possible to hear ail four musk tracks at once tender 
QuickTmie for Windows 2.1.2? 


You can do live mixing of your four QuickTime movies only if your Windows 
system has four MIDI output devices. Most systems have only one. All Windows 
applications suffer from this limitation unless they’re clever enough to mix the 
tracks on the fly but none seem to do this. 


For now, you must pre-mix the four music tracks from the four movies into one 
music track in one movie. You won’t be able to do live mixing unless you write 
your own MIDI sequencer. 


Q Can 1 play a compressed fFAVE file on the Macintosh? 

A Yes. You can use the Sound Manager to play a compressed W^AVE file on the 
Macintosh, but how easy it will be can vary greatly, depending on the t 3 ^e of 
compression. 

If the W^AVE file is compressed using plaw, your program will have to use either 
SndPlayDoubleBuffer or SndDoCommand with bufferCmds to play the sound 
(QuickTime cannot currendy be used). This means that you’ll have to parse the 
WAVE header yourself and interact with the Sound Manager at a lower level 
than is possible by simply calling SndStartFilePlay. 

Currendy, you can’t play an IMA-^\DPCM compressed W^AVE file as easily as a 
'ulaw’ compressed WA\T file, because the data stream of a sound compressed 
with Windows’ IA4A-ADPCM compressor differs from the data stream of the 
same sound compressed with the Macintosh’s IMA compressor. To play an IMA- 
ADPCM compressed WAVE file on the Macmtosh, your application will first have 
to decompress chunks of the sound into memory, then have the Sound Manager 
play those chunks. You can do this either by calling SndPlayDouhleBuffer or fey 
using bufferCmds. Of course, if the uncompressed sound fits completely into 
memory, you can simply use SndPlay on that one uncompressed buffer. 

To play a WAVE file that uses a custom compression algorithm, you can eidier 
write your own ’sdec' (sound decompressor) component or simply have your 


MACINTOSH Q&A 107 




program decompress the sound itself As before, if you can fit the decompressed 
sountl in memory, you caji use any Sound Manager routine to play it. If you 
can’t, you’ll have to decompress it in chunks and use SndPlayDouhleBuffer or a 
bufferCmd to play each chmik If you write your own 'sdec', of course, you can 
use any Sound Manager routine that will play an arbitrarily compressed sound, 
but be sure to indicate that the sound is compressed with your compressor so 
that the Sound Manager will know to call your sdec’. 


Q 

A 


How do I make a sotaid that wUi play on both Macintosh aitd PC computn^s? 

This is actually easy, as long as you don’t want to play compressed sounds. We 
recommend that you use WAVE files for both systems, since they’ll play easily 
on the Macintosh. (See the previous answer for some tips to help you play WAVE 
files on the Macintosh.) Note, however, that tliere are many other formats that 
will work, including AIFF and QuickTime. 


Q 


How can I access the “Sf/ Utilities Pattern.^ pattern^ (Thispattmi^ used as a backp^und 
by cef-tain syste?n utilities like Find Fik^ is nomiaily set by holdmg down the Option key 
in the Desktop Patterns conti'ol panel.) 


The Desktop Patterns control pane! uses resources of type 'ppat’ to store both 
desktop and utilities patterns. The 'ppat' resource is stored in the System file in 
your System Folder; the desktop pattern has an ID of 16 and the utilities pattern 
has an ID of 42. Since this isn’t documented, it could he subject to change, so 
you should be careful when using it. 


Here’s a snippet of code that shows how you can get the utilities pattern and 
then draw with it: 


PixPatHandle ppatHandle; 

Rect destRect; 

ppatHaudle == [ PixPatHandle) GetPixPat (42); 
if (ppatHandle 1= NULL) { 

SetRect{ fiideatRect, 15, 125, 197, 164); 
FraineRect (sdestRect); 

FillCRect(sdestRect, ppatHandle); 
DisposePixPat{ppatHandle); 


Q 


/ discovered that if I hold down the Command key and click In the size box of a wifidow, 
I can make the window bigger thaii the width 1 pass into Grow IVindow. The size box 
works as expected when the Command key isn V used. This seems to happen in every 
application Tve tiied. / haven V been able to find any documentation disaming the 
relationship between the Cirmmand key and the size box, / really need to limit the width 
of my windows. Why is this happening and how can 1 work around it? 


Back in the old days when the Macintosh had a 9-inch screen (384 x 542 pixels), 
a lot of developers didn’t follow^ Apple’s guidelines for wdndow sizes and hard¬ 
coded the sizeRect given to GrowM^dow' based on this small size. 
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MTen the Macintosh IT was introduced in 1987, Apple engineers felt it would 
he frustrating for users not to he able to use the whole area of the new 13-inch 
monitors. So Apple implemented the ''Command-key grow” feature that you 





discovered, which allowed users to get whatever size they wanted. However, this 
feature was not without consequence to some applications, whose code couldn’t 
handle 1 arger-than-expected window sizes. The “Command-key grow” feature 
is documented on page 209 of the old Imide Macintosh Volume V, but wasn’t 
documented in the newer imide Macintosh series* 

It’s trivial to deal with this feature if you really need to limit the window size: 
simply check the size returned by Grow Window, and if it’s larger than you 
allow, reduce it to your maximum allowed size before calling SizeWindow* 


Q 


Vve noticed that calling DeleteMcmifteTn 7nangles the ?nenii data when bandiing menu 
hmts with strings that have hetwem 251 and 255 characters. Does the Menu Manager 
have a prohlmt when handling menu hems with strings that long? 


Yes, this is a problem, but it hasn’t been documented in any Inside Macintosh 
books. The Menu Manager assumes that a menu item string isn’t longer than 
250 characters, so you shouldn’t have menu items longer than that* 


IVhen I me ShowDragHHite with a picture fdiing tny windtni\ it highlights only the 
areas that are the same as the Imck^wund of my windtrw. Is there any way to fix this? 


Yes* ShowDragHiiite isn’t very savvy when overlaying image data other than the 
background colon l"he problem lies in QuickDraw’s hilite mode* The operation 
of this mode is based rather coarsely on the background colon WeVe working on a 
fix for this problem, and eventually hilite mode will work significantly better in all 
cases, including that of selecting cells in lists drawn by the standard LDEE Until 
then, your only alternative is to implement your own version of Show'DragHtlite. 


The question then becomes what color to use. Depending on your circumstances, 
yc3u may want to use black, white, or perhaps even inversion, although you 
should try to avoid inversion against complex images if at all possible, since it 
can be ogly and confusing* Should you decide hilite mode is insufficient, it’s up 
to you to decide how best to draw your highlight. 


Q 


Sometimes my applkation^s calk to the Drag Manager fail with a -600 (procNotFound) 
error This isni one of the errors listed for these calls. UHsafs up? 


A 


There are three known common causes of this error: 


• The use of high-level debuggers — Since the Drag Manager interacts heavily 
with the Process Manager, as does the typical high-level debugger, conflicts 
inevitably develop* There’s no workaround for this problem except to ask 
your debugger vendor to improve the debugger’s behavior w^hen debugging 
Drag Manager code* If your code is encountering such a problem, it should 
run fine when the debugger is not involved* 

• Passing TrackDrag an event record whose where field is expressed in local 
coordinates — Such where fields often point outside the window in which 
the drag originates. {This can also cause a crash, but sometimes simply 
results in a -600 error*) 

• Attempting to use the Drag Manager with Text Services Manager windows 
when the gestaltDragMgrFloatingWnd bit isn’t defined in the response to 
the gestalrDragMgrAttr Gestalt selector — The value of this bit denotes 
whether a Drag Manager bug with TSM windows is fixed on the system 
your application is running under* 
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In the last two cases, the Drag Manager has a hard rime associating the source 
window with a process. Some operations can succeed even without a clear owning 
process, so the Drag Manager limps along as well as it can for a while in the 
hopes that it won^ be asked to do anything that requires a ProcessSerialNumber. 
Wlien it is asked, the operation fails. 


Q 


Fvejmt i?nple?mnted a DragDrawingProc. To start, Pve tried simply to duplicate the 
default behavior of the Drag Manager (so that it will look as if I had not in fact 
attached a DragDrawingProc). Unfortunately, when the user drags into a valid drop 
area and the potential drop 7Tceiver calls ShuwDragHilite, my DragDrawingProc 
seems to be responsible for leaving a trail of pixels on the screen. What am I doing wrong? 


This happens because the DragxManager doesn’t always pass the entire “old” or 
“new’’ region to the DragDrawingProc. Below is a hmcrion that mimics what 
the Drag Manager does when you don’t attach a IJragDrawingProc to a 
DragReference before calling TrackDrag: 


static pascal OSErr LikeDefaultDragDrawiTigProc(DragRegionMessage message, 
RgnHandle showHegion, Point showOrigin, RgnHandle hideRegion, 

Point hideOrigin, void *dragDrawingHefCon, DragReference theDragRef) 

{ 


OSErr 

RgnHandle 

long 

Pattern 


err = noErr; 
xorMe; 
oldA5; 
gray; 


switch (message) { 

case dragRegionBegin s 

oldA5 = SetA5((long) dragDravingRefCon); 
gray = gd.gray; 

SetA5(oldA5); 

PenPat(sgray); 

PenMode(notPatXor); 
break; 


case dragRegionDraw: 
xorMe = E9ewRgn(); 
if (l{err = MemError())) { 

XorRgn(showRegion, hideRegion, xorMe); 
PaintRgn(xorMe); 

} 

break; 


case dragRegionHideI 
PaintRgnfhideRegion); 
break; 

} 

return err; 

} 

'fhe call to XorRgn is the key. It’s also very important to pass the correct value 
for the dragDrawingReRfon to SetDragDrawingProc: 

SetDragDrawingProc{dragRef, LikeDefanltDragDrawingProc, 

(void*)SetCurrentAS()); 


no cfevefop Issiffi 2*? March 1997 





Note that the above works for 6B0x0 eode; UniversalProcPtr creation has been 
omitted for simplicity. 

By the way be careful not to mix the use of SetDragDrawingPrtK: and 
SetDraglmage, See Technote 1043, “On Drag xManager Additions,” for details. 


Q 


When my appUatthn calls the Drag TrackDrag routine and the user drags 

text out of my applkation onto the desktops a clipping file appears. At least it does under 
Systmt 1.5; under SysfCTn l.f nothing happens. Why? 


In Systems 7.1 through 7.1.2, the Drag Manager is implemented by means of 
multiple extensions {all in the Extensions folder), and various capabilities 
become available according to which extensions are installed. You can’t count on 
any of these extensions being installed, so if you want your application to use 
the hill functionality of the Drag Manager under these system versions, your 
application’s installer should install these extensions. 


Some systems may already have older versions of Drag Manager components, 
in which case you may want to replace them with new'er versions. If you do, be 
sure to install all of die appropriate files to ensure version parity on the user’s 
system. 


Table I describes which components implement which functionality on which 
system. It’s provided only for purposes of installation. Your application should 
not attempt to determine what functionality is available according to which files 
are installed (since users may have enabled some extensions without restarting, 
and since different versions of the system require different sets of extensions). 
Your application should instead test for Drag Manager functionality with the 
gestaltDragMgrAttr Gestalt selector. 

In System 7 and 7,0.1, the Drag Manager is supported, but only for intra- 
application dragging. This makes it less desirable to install the required 
Macintosh Drag and Drop extension, because it provides nothing that c-an’t be 
implemented through judicious use of QuickDraw, the Window Manager, and 
OSEventAvaiL 


In System 7,5, the picture is equally simple but significantly richer. All Drag 
Manager functionality is huili into or installed with the system. 


Table 1* Drag Manager files required for individual features 


Feature 

System 7,1 

System 7 Pro (7,1,1) 

System 7,1,2 

Interoppii cation 
drag ond drop 

Macintosh Drog and Drop, 

Dragging Enabler 

Macintosh Drag and Drop 

Macintosh Drag and Drop 

Drag and drop 
to/from Finder 

Macintosh Drag and Drop, 

Dragging Enobler, Finder 7.1.3 

Mocintosh Drag ond Drop, 
Dragging Enabler 

Macintosh Drag and Drop, 
Dragging Enabler, Finder 7.1.3 

Clippings 

Macintosh Drag and Drop, 

Dragging Enabler, Finder 7.1.3, 
Clipping Extension 

Macintosh Drag and Drop, 
Clipping Extension 

Macintosh Drag and Drop, 
Dragging Enabler, Finder 7. L3, 
Clipping Extension 


Nolei You should not mstoll Finder 7.1.3 on user syslems; in fact, there isn't on easiiy available license for shipping it. However, before 
System 7.5 it was the only way for developers without System 7 Pro (which includes Finder 74.3) lo debug their code, so its use is 
documented here for historical reosons. 
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Undei- MacTCP a7id Open Transport IJLx^ ifFm using a Hosts file and I call 
AddrToNa?ney the na?ne resolves to the cofrect address. Under Open Transport LI It 
returns an authNameErf: IVhaFs gomg on? 

Open Transport version 1,0:8 mapped nanie-to-address and address-co-name 
translations into the same cache, and searched the cache whenever either a 
name-to-address or an address-to-name mapping was requested. Sounds good, 
right? The problem is, it broke several server load-sharing implementations that 
registered a service name as a single alias for a list of CNAMEs, each of which 
pointed to a server running the service. Under the fonner caching scheme, 
load-sharing techniques that depended on reverse [ookups didn't work for the 
Macintosh — they'd always wind up with the same host name and hardware 
address for the original alias. 

As a result, Open Transport 1J no longer caches address-to-name mappings 
(PTR records), nor does it search the name-to-address cache for address-to-name 
requests. (The treatment of CNAME records received was also modified, but 
that's irrelevant to your question.) Instead, it queries the configured domain 
name servers; apparently you got no authoritative information from any of them 
(or perhaps you weren't using them at all). 

Strictly speaking, the behavior you're now seeing is more correct than what you 
saw before. DNS A resource records map names to addresses. To map an address 
to a name, you need a P'TR record. I'he previous behavior of the MacTCP and 
Open Transport TCP/IP DNRs, treating the one as the mirror image of the 
other, was incorrect and has been changed accordingly^ 

The Macintosh Hosts file historically did not support I^FR records, and does 
not support PTR records now. To do so, those records would have to be cached, 
once again breaking the load-sharing schemes. The only resource records the 
Hosts file supports are: A (name to address), CNAME (alias to fully qualified 
domain name), and NS (domain name server's fully qualifiet! domain name). If 
you need a PTR mapping, you must register it witli your local domain name 
server administrator, nr maintain it within your own cotie from the results of 
your earlier name-to-address request. 


Tm writing an application using the native Open T'ansport APIs. My original 
intenthn was to ship o?ily a 6tH()xO version of the application^ inn Tve heard that this 
won^t he cojnpa tilde with future veisiom of Ope?! Transport. Is this trnei^ 

Yes. We strongly recommend that you ship all native Open transport applications 
as fat applications for maximum speed and compatibility^ 

Under System 7, Open 'Pransport provides native APIs for both 680x0 and 
PowerPC clients. This allows 680x0 Open Transport clients to operate under 
emulation on a Power Macintosh. This won't be supported under fiiture 
systems because they won't support the Apple Shared Library Manager, the 
dynamic linking technology' used by 680x0 Open Transport clients. Tabic 2 
summarizes this infonnatiun. 


What are the dijferent Gestalt sekmrs for MacTCP, Open Transport^ and AppleTalk? 

The Gestalt selector for MacTCP is mtep*. MacTCP versions 1.0 through 
L03 didn't register this selector. Versions 1.1, 1.1,1., and 2.0 return 1, 2, and 






Table 2. Open Iransporl- compatibility 


Open Transport version 

680x0 client on 680x0 

680x0 client on PowerPC 

PowerPC client 

Open Transport 1,0.x 

N/a‘'1 

YesP‘3,41 

Yes 

Open Transport 1.1, System 7 

Yes 

Yes 

Yes 

Open Transport 1.5, System 7 

Yes 

Yes 

Yes 

Open Transport, Future systems 

n/a‘^' 

Nal*' 

Yes 


Notes: 


1. Open Transport 1.0.x was never shipped or supported on any 680x0 Mocinfosh, 

2. You must Jink with the Open Transport 1.1 b6 or loter librories for this to work, 

3. Obviously you must not call routines that were introduced with Open Transport IJ . 

4. Support for 680x0 clients on PowerPC isn't well tested under Open Transport 1,0.x. For this and many other reasons, 
you should implore your users to upgrade to 1.1, 

5. Future systems will be PowerPC only. 

6. Future systems won't support ASLM, so rt's not possible for it to support Open Transport 680x0 clients. 


respectively. If Open Transport is installed, 4 is returned. A value of 0 is returned 
if the driver is not opened. 

The Gestalt selectors for Open Transport are {t<^staltOpenTpt and 
gestaltOpen rptVersions. You can test whether Open Transport and its various 
parts are available by calling the Gestalt functi(}n with the gestaltOpenTpt 
selector. The bits currently used are defined by constants in OpenTransport.h, 
as follows: 

enum { 

gestaltOpenTpt = ^otan’, 
gestaltOpenTptPresent = 0x00000001, 
gestaltOpenTptLoaded = 0x00000002, 
gestaltOpenTptAppleTalkPresent = 0x00000004, 
gestaltOpenTptAppleTalkLoaded = OxOOOOOOOS, 
gestaltOpenTptTCPPresent = 0x00000010, 
gestaltOpenTptTCPLoaded ^ 0x00000020, 
gestaltOpenTptHetwarePresent - 0x00000040, 
gestaltGpenTptNetwareLoaded ^ 0x00000080 

}? 


If Gestalt returns no error and responds with a nonzero value, Open Transport 
is available. To find out whether Open Transport AppleTalk, TCP, or NetWare 
is present, you can examine the response parameter bits as shown above. For 
example, if you pass the gestaltOpenTpt selector to Gestalt, a result of 
0x000000IF means that Open Transport is present and loaded, the AppleTalk 
protocol stack is also present and loaded, and the TCP protocol stack is present 
but mt ioaded. 

The gestaltOpenTpt Versions selector is used to determine the Open Transport 
version in NiimVersion format. For example, passing the gestaltOpenTptVersions 
selector tit rough a Gestalt call or MacsBug to Open Transport version 1.1.ih9 
yields a result of 0x01116009. {Note that Open 'Transport versions 1.0 through 
1.0.8 did not register this selector.) For more information on Apple’s version- 
nmnbering scheme and the NumVersion formal, see Technote OV 12, ''Version 
Territory,” 
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For AppleTalk, the Gestalt selectors are 'atkv' (no constant defined) and 
gestaltAppleTalkVersion. The gestaltAppleTalkVersion selector was introduced 
in AppleTalk version 54 to proinde basic version information. Calling Gestalt 
with this selector provides the major revision version in the k>w-order byte of 
the function result. For example, passing the gestaltAppleTalkVersion selector 
in a Gestalt call or thrctugh MacsBug with a result of 0x0000003C means that 
AppleTalk version 60 is present. {Note that the gestaltAppleTalkVersion selector 
is not available when AppleTalk is turned off in the Chooser.) 

The 'atk"v' Gestalt selector was introduced as an alternative in AppleTalk version 
56 to provide more complete version information via die Vers' resource. For 
example, passing the 'atkv' selector to AppleTalk version 60 through a Gestalt 
call or MacsBug yields 0x3Cl08000. 


(k Pm wyiting mi Ope^n TmnspoJt module that confoTTfts to the Tmnspon Provider 
Interface (TPl), I find that Open Trmupon passes data to ?ny TPl module using 
M_DATA message blocks^ rather than M_PROTO message blocks with PRIMjype 
hewgT_DATA_REQ. WhaPs going on? 

A The answer can be found at the end of the description of T_DATA_REQ in 
Appendix A-2 STREAMS Modules and Drivers {UNIX Press, 1992): 

The trampoir providet'^ must abo reco^tize a message of one or more M_DATA 
message blocks tvithout the leading M_PROTO message block as a T_DATA_REQ 
primitive. This message type will be initiated jrom the write (BA_OS) operating 
system service routine. 

Open Transport deliberately uses this variant behavior as an oprimizadon. By 
using M_DATA, it avoids ailocadog a buffer for the M_PROTO header. Since 
every memory allocation takes time, avoiding this one makes the system faster. 

This behavior isn't seen on expedited data because the specification doesn*t 
allow for this optimization on T_EXDATA_RFQ, 


Q 

A 


Hofw can I launch a fiorepy^otmd'^ task to rim in the hackgrvund? 

You should use the LaunchAppltcadon call in the Process Manager with the 
launchDontSwitch flag set in die launchCkmtrolFlags field. For more 
infomiatitm about LaimchApplicadon, see Imide Macintosh: Processes^ C.hapter 2. 


Q 


Tackling a difficult problem in my applicamn had put me in a foul moody when a 
collea^ie pointed out that / was being awfully ""tetchy. ” / told him the correct word is 
""touchy^ ” and sure enough 7ny spelling checker doesn V recognize ""tetchy. ” IVIjoIk right? 


Your colleague wins this tme. The Oxford Englbh Dictionafy does recognize 
“tetchy,” which means “easily irritated or made angry.” It lists many variants for 
the spelling of this word, including techy, techie, teachy, teechy, tetchie, tecchy, 
dtehie, tichy, dtchy, tertchy, tatchy, and tachy. 


These cinswers are supplied by the lechnied 
gurus in Apple's Developer Support Center. For 
more answers^ see the Technical GJ&As on this 
issue's CD or on ihe World Wide Web ot http:// 


WWW, de vwor Id. a pple. com / d ev/tec hq o, sh tm I, 
(Older Q&As con be found in the QM Tech notes, 
which ore those numbered in the 500s,) " 


114 


develop l&sue 29 March ]997 








KON & BAL'S PUZZLE PAGE 


AppendDITL Apoplexy 


See if you can solve this puzzle in the form of a dialog between a pseudo 
KON (Bo^b Johnson) and BAL (Martin-Gilles Lavoie). The dialog 
gives clues to help you. Keep guessing until you're done; y<yur score is the 
number to the left of the clue that gave you the correct answer. Even if 
you never run into the particular problems being solved here, you'll 
learn some valuable debugging techniques that will help you solve your 
(mm prog amming conundrums. And you'll also learn interesting 
Macintosh trivia. 


MARTIN-GILLES LAVOIE 
AND B03B JOHNSON 


BAL Well, KON, Fm very disappointed to announce that IVe fallen back to 
the level of a newbie Mac programmer and am forced to ask you a 
question whose answer is probably obvious. However, I'm stuck. 

KON An easy one? Great, weMI have it fixed in no time — and we'll give 
Puzzle Page readers a chance to get a decent score for a change. 
Details, please. 

BAI^ Fm working on a new version of our application plug-ki. One of the 
dialogs we had in the previous versions was very cluttered, and since 
we needed to add even more stuff to it, we decided to use “tabs” to 
group related options. But now^ the system crashes shortly after calling 
AppendDITL. 

KON That’s a well-traveled piece of the system. Why would you crash and 

no one else? Let’s check for reported bugs...just as I thought, Developer 
Technical Support has no bugs listed for AppendDITL. Is the bug 
reproducible? 

BAL 100% reproducible, and always after calling AppendDITL. 



MARTIN-GLLLES LAVOIE (mouser^zercom.nef) 
constantly looks For more efficient means oF using 
his hands. AFter experimenting with branch- 
pred icti on-e n h a need , tri state-b i n a ry-e n h a need , 
and Floating-point-enhanced finger-coded binary 
techniques (pioneered by Tobias Engler in develop 
Issue 21), he went on to make a medieval ring 
mail consisting of over 26,000 rings. He hopes 
to moke adequate use oF his hands on his vacation 
in France, where he^l be touring medieval festivals 
and castles. Then he'll be back in Montreahbosed 
Globimoge, Inc., where he works on prepress- 
related uKlities ond automotion software. * 


B03B JOHNSON |bo3b@opple.comk 
whose name is pronounced "Bob/ hos been 
programming the Macintosh seemingly Forever 
and still hasn't lost interest (though it was touch- 
ond-go there For a while). Having recently 
returned to Apple's Developer Technical Support 
group aFter a long sHnt as a dedicofed stacker, 
windsurfer, and pursuer of arcane knowledge^ 
Bo3b is rediscovering the joys of working for a 
living (ar^d has actually found a few). Getting up 
in the morning^ however, remains a serious 
challenge. * 
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KON 

BAL 


KON 
TOO BAL 

KON 

BAL 

KON 

90 B^\L 

KON 


BAL 

KON 

80 BAL 


\\Tien is this AppendDITL call made? 

The plug-in code runs as part of the host application and monitors 
activity within a floating window. One button in this floating window 
brings up a dialog containing a list of items that can be edited with a 
second dialog that comes up. The second dialog has tabs; when it*s 
brought up, a call to AppendDITL is made t(> add the dialog items for 
the first tab panel into this dialog. 

How does it crash, exactly? 

A little while after AppendDITL exits, the dialog is visually messed 
up, and the system drops into MacsBug with a bus error. Also, the 
application heap is usually corrupted. 

This is a code resource, right? C]ode resources can\ have A5 globals, so 
any globals would cause you to “color outside the Unes.” Arc you using 
globals? 

The application plug-in interface file requires the use of globals, but it 
was built with Code Warrior, which uses register A4 as a code resource's 
globals pointer. 

Wfliat if x\ppendDITL trashes A4 during execution? That would cause 
some of your user item procedures to fail while trydng to access 
globals. 

Well, let's check, WTien the dialog is first brought up and items are 
being appended to it for the default tab, it immediately crashes. Here, 
witness the disaster... 

Indeed, it crashes really hard. MacsBug is alive, but the system is barely 
alive; I can't escape the application with es. UToa! 1 can't even reboot 
with rb. Let's try that again, and watch AppendDITL. We do an atb 
AppendDITL, then trace over the call. Nope, A4 is untouched by 
AppendDITL, In addition, die heap was corrupted only after several 
AppendDITL calls, so Fd say A4 is sohd and not the prohlem. 

Time for the Vulcan Nerve Pinch? 

Control-Command-Power? Indeed! While we're rebooting, can I see 
the code wftere you add items to this dialog? 

My plug-in uses code that IVe used in a standalone application, Tliis 
code has worked just fine since then, and I don't see why it should 
make a difference when used in a code resource. It's pretty much by 
the book. When the user clicks the tabs in the dialog, we make a 
DITL content switch using this code: 

//At this point, clickedTab contains a DITL ID corresponding to 
// the clicked tab DITL ID, 'kPanelBase' is the number of items 
//in the base DITL {ID 29000), 
if (gCurrentPanel 1= clickedTab) { 

short numltems = CountDITL(theDialog)j 
if (numltems > kPanelBase) 

ShortenDITL(theDialog, numltems - kPanelBase)? 

Handle ditIResource = GetResource {' DITL', diekedTab); 
AppendDITL(theDialog, ditlResource, overlayDITL); 
ReleaseResource(ditlResource); 
gCurrentPanel = clickedTab? 

> 
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The first time around, the ShortenDITL routine isn^t called because 
numlcems is equal to {but not greater than) kPanelBase. I verified this 
at run time with source-level debuggers, 

KON Tm wondering about the ReleaseResource right after the AppendDITL 
call. 


70 BAL 

KON 

BAL 

KON 
65 BAl. 


KON 

KON 


BAL 

KON 

60 BAL 


Inside Macintosh recommends doing this to avoid using altered DITL 
resources if we later display a dialog whose item list was previously 
altered, Aktr the crash, 1 examined the content of the application heap 
to see if any expected resources were missing. I used hd r to dump all 
resource information in the current heap; 1 made sure that all my 
resources were loaded and that my code isn't inadvertently using the 
host application's resources. 

Well, we know hiside Aiacintosh isn’t always rights so let’s display the 
DialogRecordjtems handle after AppendDITL. We’ll find this handle 
with thePort and then dm , dialogrecord. 

The size of the handle is different after the call, and it appears to mate 
a copy of the DITL into this handle, so calling ReleaseResource 
shouldn’t be a pn^hlem. 

Did someone patch AppendDITL? Or perhaps the dialog underneath 
is causing a conflict? 

Let’s loot at AppendDITL with the debugger. Do an il AppendDITL. 
Hmm, the code is still in ROM at CommToolboxDispatch, so it’s not 
patched. You also wouldn’t expect any conflict between the two dialogs 
on the screen, because you have to pass the DialogPtr to AppendDITL, 
which gives it the exact DialogRecord. 

OK, so far my ideas aren’t panning out. But I notice that although it 
alw^ays crashes, it doesn’t seem to crash the same way every time: 
sometimes it takes two AppendDITL calls and sometimes one, 

MTiat could make it do that? 

It’s probably using some nearly random chunk of memory. Let’s make 
it more reliable in the way it crashes by turning on heap scramble with 
hs. Do you want to use QC or Jasik’s debugger instead? They’re an 
even stronger way to make it more repeatable. 

No, this still seems like an easy bug, so let’s stick with MacsBug. That 
hs seems to help. 

As near as I can cell, there’s some problem with the fonts. Most of the 
crashes happen w'hile it’s drawing text. It nearly always crashes in a 
TextBox or TESetText call, during the handling of DrawDialog. Do 
you change the fonts used to draw the dialog? 

T do. Here’s the code: 


((GrafPtr) theDiaIog)->txFoiit = Geneva; 

((GrafPtr) theDialog)->txSize = 9; 

if p({(DialogRecord*) theDialog)->textH)) { 

// This will have to come from a resource for localization. 
(*{((DialogRecord*) theDialog)->textH))->txFont = Geneva; 

(*(((DialogRecord*) theDialog)->textH))->txSize = 9; 

(*(((DialogRecord*) theDialog)->textH))->lineHeight = 12; 

(*(((DialogRecord*) theDialog)->textH))->fontAscent = 10; 

} 
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Listing 1. The ant-sized sc7 



■ IMHV tlM MiiP4H 



What exactly happens in AppendDITL when it adds text items (either 
static or editable) to a dialog whose port’s font and size were altered? 

KON Beats me. Intriguing question, though. Since it’s only display code, let’s 
comment it out* 


55 BAl^ It still crashes. 


KON Well, then it must not matter if we change the fonts in the window. By 
the way, BAL, while I don’t think this is the solution to the bug, you 
should at least use the regular calls like TextFont and TextFace instead 
of setting the fields directly, and make TextEdit calls for the parts that 
modify the TEHandle* 

BAL Oh* Right* 

KON Time to look at a stack crawl? Let’s try sc. 

50 BAL It says: 












fliuiPMi 





VI 

i\ 


lllMHi 





start of link chain does not point to a stack frame 


KON Bummer. OK, how about doing an sc7, even though it’s n<:>t as reliable? 
It won’t miss anything, but it will show up a lot of junk addresses that 
aren’t real. When you’re desperate for information, you turn to sc7. 
Here, take a look... (See LL^ing L) 

BAL Geez, KON, could we make it any smaller for our dnwiop readers? 

KON Mey, it’s not critical for them to see the details* And our lawyers insisted 

on a full disclosure of all infonnation related to finding the hug* 
Readers can always get out their magnifying glasses, if they wimt to. 

BAL Good thing it’s high resolutinn or they’d have to call the psychic 

hodine instead of just squint. 1 ley, have you ever used one of those 
magnifiers on ants? 

KON BAL, can we focus on the problem at hand? Let’s dt) the nonnal thing 
and skip all the umiamed routines, and just try to get a feel for what was 
going on. The routines that have a frame address in the second column 
are more likely to be valid calls; we can probably ignore die others. 


45 B/\L Well, there’s a call to MyWndowEvent-h00294, and one to 

MyDoStyleList+00044, both my routines* Further down are my 
DoStyleListDialog+003F0 and MyDoStyleEditor+OOOSO. Among the 
Toolbox calls of interest, there’s one to _NewDialog+00 1 C4, and later 
to _DrawDialog+0000i\, and maybe in response to that a call to 
TextWiddi+00048* 


KON The TextWidth call makes me think the Font Manager might be 
damaged* 

40 BAL Further down, without any frame addresses, we get six KillPicture 
calls, two slntRemove calls, two Jackson calls, and some odier stuff 
that implies the computer ran off through the weeds for a while before 
it finally died. Hmm.. .there’s no call to AppendDITL in the chain, 
though, and sc7 wouldn’t miss it 


KON I thought you said it crashed in AppendDITL? 

35 BAL No; to be precise, I said it crashes shortly after AppendDITL, and if 1 
comment out the AppendDITL call, the crash no longer happens, so it 
must be related. 
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KON OK, but I still think the Font Manager is trashed, because when I look 
in low memor\^ at CorFMSize, I see the font size is 4583! I'hat’s a bit 
big for this computer 

BAL Not only do fonts get smashed, but sometimes the dialog’s added 

items will draw with wacky colors. It appears that the whole graphics 
port (the current window) gets written over sometime during the 
AppendDlTL call. 

KON I ley, there’s Dave Polaschek and Quinn. Dave’s run into problems 

with AppendDlTL before, so let’s ask him about it. Dave» what exactly 
does AppendDlTL do? 

Dave Nothing too tricky: It locks the new* DITL handle and then steps 

through the items in the list, loading and installing each one into the 
dialog. It uses GetNewControl for controls, copies in the static text 
items, and loads and puts the handles to PICT resources in the DITL. 
W'Tien it’s done, the new DITL handle is unlocked but left in memory* 
There’s an old version of the source code in Technote PR 09, “Print 
Dialogs: Adding Items.” 

KON Any nasty behavior or bugs that you know about? 

Dave The only common problem I’ve heard of is with 'ictb' resources. Are 

you using them to specify fonts and sizes or color tables for your DITLs? 

BAL No. Also, no font-specific action is taken at run rime — I don’t call the 
Font Manager, and 1 don’t directly call ATM. The only thing related 
to fonts that I can see is that the dialog’s font and size are changed to 
Geneva 9 before the AppendDlTL (w^hich goes against guidelines for 
localization). Wait, there’s also a font pop-up menu that’s being 
updated with the current font list wLcn the dialog gets called up. But 
both these things worked before I started playing with AppendDlTL, 

KON Still, those ’icth' resources sound suspiciously like what weVe seeing. 
Quinn, have you heard of any Imgs relating to Herb' resources? 

Quinn Nothing specific, just what Dave said: they’re more trouble than 

they’re worth. Have you looked for ’ictb' resourees in the heap? Try 
doing an lid ictb. 


KON Hey, there are a bunch in there! Hmv about in the resource fork? I’m 
ck)ing an rd ictb too. 

20 Quinn Sure enough, there are some in the resource fork. Those ‘ictb’ resources 
are only used to change the look of the dialogs; they aren’t required. 
Since we don’t trust those things, why don’t you delete them in a copy 
of the plug-in? Mliere’s ResEdit? 

KON OK, I cleared them out; now let’s try it again. Dang! It still crashes, 

and the same way. I would have bet that was it. How many points do I 
have left? 


Quinn Not enough to clear your karma point deficit. V\Tiy don’t you do an 

atb DrawDiaJog, and then just an atb so that we can see what happens 
before it dies. We won’t see any PowerPC calls, but this is ail 68K code 
an>"way. 

KON OK. The last dialog-related thing it did was call TETextBox to draw^ 
one of the static text items — another hint that it’s a font problem. 

Dave To find this, you’ll need to reduce the number of variables. See if havmg 
fewer items in your dialog changes anything. Maybe a corrupted item 
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or a resowce conflict is causing the problem. You said you’re using at 
least one pnp“up menu, right? Is its menuHandle properly loaded? 

15 BAL I tried a number of variations on what youVe suggested; I simplified 
the code in all these ways: 

• I disabled any filter procedures passed to ModalDialog, 

• I removed any user item procedures. 

• I removed any code-handling items in tab panels. 

• I converted (one by one) all items in the first tab panel to static text 
items, relaunching die host application every time. 

• I reduced the number of items in the first tab panel, down to six 
static text items, 

• I removed any code having to do with the dialog’s base elements 
(those that stay regardless of the current tab), 

• 1 converted the base dialog’s elements to static text. 

• I moved items around so that appended items wouldn’t be 
surrounded by PICTs that fonn the frame of the tal) area. 

None of this worked. In all cases, the same bad behavior occurs after I 
come out of AppendDITL. I even tried using just a single plain button 
and one static text item, but it still trashed the heap. Furthermore, all 
the pop-up menus in this dialog (and its tab panels) use different 
menus, and all menus are loatled and installed during startu]!, with 
InstallMenu(theMcnuHandle, -1). 


KON Well, this is getting even more interesting now. rm walling to bet that 
this is a bug in AppendOrFL, hut I can’t put my finger on it just yet. 
To simplify even further, let’s make a smalt test application with only 
the code that luintiles the ilialog. 

Dave Ciood idea. But I’m hungry, so Til leave you to it. Anybody w^ant to 
have dinner? 


Quinn I’ll join you — tluiugh I like the taste of freshly killed hug better, 

KON That leaves it to us, BAL. WeVe making strong prf)gress mm, though, 
so we should have this one crushed in an hour or two. 


BAL KON, weVe been looking at this for over five hours nf>w, we’re nearly 
down to 10 points, and we still can’t find it. 

KON I’m just going to make a simple application that creates the dialog using 
your code. And I’ll copy the resource fork of your plug-in so that we get 
all the DITLs. 1 want to rule out the host application having any effect. 


10 BAl^ OK, excellent! And it still crashes with the test app. Now we can keep 
simplifying until we find the offending code. 

KON Let’s take a big simplifying jump and change the dialog to just a control 
and a static text in each tab panel, as in your test. 


B.AL Huh! It still crashes in this nearly trivial case. I guess we can’t blame 
the host application. 

KON Now let’s keep trying to find where it stops crashing. Fve removed the 
entire content of the tab panels’ DITLs imd replaced their content 
with a single plain button straight out of ResEdit’s tool palette. 
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Each button on each tab panel says something different, just to make 
sure theyVe actually removed H'hen they’re tabbed out. 

BAL Look at that, it worked! I doubt we have a limit of one item per 
AppendDITL — that would l>e ridiculous. 

KON 1 agree. So it must have something to do with static text. Fonts, I tell 
you! Fonts, fonts, fonts, fonts, fonts! 

BAL Easy, KON. Well find it. Let’s put the static text items back to make it 
crash again. 

KON OK, now let’s trim the icons and other junk out of the resource fork, to 
be sure it’s not interfering, and to make it as simple as we can get yet 
still crash. 


5 


BAL Hey, there are 'ictb' resources in our test app! 

KON They must have come from the plug-in when we copied die resource 
fork. 


BAL And look at this. My phig-in file has grown in size bemeen its 

installation and its first run in the host application. I don’t modify my 
own code in this plug-in — somediing’s fishy. 

KON You said you weren’t using any 'ietb’ resources, yet earlier we saw lots 
of them in your plug-in. 

BAL Just a second, while I cal! the host appfication’s niLmutacturer... Ahem. 
Get diis: They warn me to make sure to have an 'ictb' resource for 
every 'DITL^ resource in a plug-in file. If any are missing, the host 
application adds empty *icth' resources for what it thinks are ^‘defieient” 
plug-in files. Lm very curious about why the host application requires 
tile presence oTicth' resources in plug-ins. 

KON D’oli! The host application is moditying your resource fork? That 

explains why our 'icib'-deleting experiment didn’t work. Sure enough, 
if I delete the 'icib' resources from the test app, it works fine. 

BAL Obviously the host application doesn’t know I’ll be using some of 

those DTTLs to expand another DITL, The Dialog Manager ends up 
having too few 'ictb’ entries for the number of items in the expanded 
dialog, and when it gets to the end of the 'ictb' resource that the host 
apjilicatioii created, it starts reading garbage from memoiy, trying to 
set fon ts, sizes, and colors. 

KON The Dialog iVlanager sets up the 'dctlf and ’ictlf data structures only 
when the dialog is created, and doesn’t change them for AppendDITL? 
That docs it, I’m fifing a hug against AppendDITL. Let’s see, that’s 
#1377732. 


BAL The static text items are a bit more fragile in this case, which is what 

we found with that test of having one static text item. Buttons just have 
a Control Record — and a color table, which only causes fimny colors 
to appear if the Dialog Manager is using random bytes out of memory. 

KON Of course! For static or editable text items, it blindly goes off the end 
of the handle, using whatever jiiiik is in memory as a txEont, txTace, 
txSize, or color table. Mtiien it set the font to number 43003, the size 
to 15433, and so on, the Font Manager was none too pleased. 

BAL I added an empty 400-byte 'ictb’ resource to my project, with the ID 
ot the base dialog. This is enough to accommodate this dialog’s items, 
plus any items I add through AppendDITL. Everything works fine now. 
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KON Hot dog! I knew we were going to crush this thing before too long. 

You have no idea how glad I am that this one has been killed. Well, 
actually, I bet you do; it stumped us for seven pages. 

BAL The host application's manufacturer also told me they need to add 

'ictb' resources in order to solve an old problem where plug-ins used 
dialog windows with the same IDs as some of their application’s dialog 
window^s. Wien these dialog windows were loaded by tlie system, the 
system would look for irs associated 'ictb' resource with GetResource, 
wdiich looks tlirongh the resource chain until it finds one. Sometimes it 
would pick an 'ictb' in their application, which wasn't suitable for the 
plug-in’s dialog window, causing the same kind of problems weVe 
experienced with my plug-ie. Watch me never assume w^hat’s in my 
resource fork from now on! 

KON Nasty. 

BAL Yeah. 


SCORING 

70^100 How would you like to work in Apple DTS? Today? 

45-65 How obout a contract os o Webmaster? 

25-40 We hear that the Highway Deportment is hiring. 

5-20 Don't give up your day job,* 

Thanks to Dave Polaschek, Quinn 'The Eskimor, KON (Konstantin Othmer), ond BAL (Bruce Leak) for 
reviewing this column.* 


lllant to shout off your cool code? 



YOUR NAME HERE 


Do you have code that solves a problem other Macintosh 
developers might be having? Mliy not show it off by writing 
about it in droelop} We're always looking for people who might be 
interested in submitting an article or a eolunm. If you’d like to 
spodight and di,stiibute your code to diousand,s of developers of 
Apple products, here’s your opportunity. 

If you’re a lot better at writing code than writing articles, don’t 
worry^ An editor will work with you. The result will be something 
you’ll be proud to show' your colleagues (and your Mom). 

So don't just sit on those great ideas; feel the thrill of seeing them 
published in devekpl 

To receive our Author’s Guidelines, editorial schedule, and 
information about our incentive program, please send a message 
to deveIop@apple.com, or write Caroline Rose, Apple Computer, 
Inc., 1 Infinite Loop, Cupertino, CA 95014. 
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SIZE resource, accepting remote 
events 75 

Size Window, QuickDraw 3D 
Viewer and 25-26 
smFontForce variable (Script 
Manager) 36-37 


INDEX 1 27 




SndDoCommand, Macintosh 
Q&A ^07 

SndPlay, Macintosh Q & A 10/ 
SndPI ayDou bleBuflfer, Macintosh 
Q& A 107, 108 
Sound xManager, playing 
compressed WAVE files 
(Macintosh Q & A) 107-108 
StandardGetFile, QuickDraw 3D 
'Wewer and 10 

state machine (NTE) 83-85, 94 

T 

T_DATA_REQ (Open Transport), 
Macintosh Q & A 114 
temporary objects (OpenDoc) 28 
ITSarnple 36 
‘‘Testing Iwo-Byte Script 
Support” (Miderson) 45 
TextEdit 

Asian languages and 32-47 
an d fon t-key b t >a rd 

synchronization 42-43 
See also TSMTE 
Text Services Manager (TSM) 
32-47 

DocnmentRecord data 
strucnire 3/-38 
fon t-key he yard 

synchremizadon 42-43 
initializing 36-37 
making applicadons TSM- 
aware 36-44 
menu handling 39-4 1 
modifying the et^ent loop 
39-42 

mouse-down event handling 
39,41 

mouse-moved event 
handling 42 

password implementation 
43 

testing for 36, 37 
TSM protocol 44-45 
wi n dow^ eve nt h an dl i ng 
41-42 

See also TSM documents 
Thompson, Nick 4 
threaded ACGI programs 53-54 
techniques for developing 
54 

3DiMF data (QuickDraw 3D 
Viewer) 

FSSpec record 16-17 
pro\iding support for ^26 
reading from a file 1 7 


readinsF and writing 3DMF 
files 15--17 

storing intorinatiDn for 
3 DiMF documents 15 
wTiting to a file 17, 18 
TSMDocumentlD 38 
TSM documents 

activating/deactivating 

41-42 

creadiig/deleting 38-39 
identifying 38 
See also Text Services 
Manager 

TSMEvent 36, 39-40 
TSMMenuSelect 40-41 
TSxM protocol 44-45 
TSMTE 32-47 

testing for 36, 37 
TSMTERecHandle 38 
TVector (OpenDoc) 29, 30 
2-bytc scripts 33 

testing 2-bytc script support 
45 

u 

UDP implementation (NIE) 81, 
82, 98-99 

pac kc 11 )0 u n d ari e s 9 8-9 9 
UPD endpoints 98 
Update Active Input /Vrea event 
(Text Services iManagcr) 44-45 
Urquhart, Ken 51 
UselnputWntlow^ (Text Services 
Manager) 44 

user interaction level prcjperty, 
v\ppleScript and 76 
“Using New^ton Internet Enabler 
to Create a Web Server” 

(Rischpater) 81-100 

V 

“Veteran Neophyte, Fhe” 
(Williams), Digital Karma 
104-106 

viewClickvScript, New' ton Q & A 
101 , 102 

viewer pane (QuickDraw 3D 
\5ewer) 8/ 25 

w 

M^aitNextEvent, ACGI and 57 
M5\STE (WorldScript-Aware 
Styled Text Engine) 36 
and font-keyboard 

synchronization 42-43 


WAVE files 

compressed (Macintosh 
Q&xA) 107-108 
multipkrfonn (Macintosh 
Q&A) 108 

Web servers. See HTFP servers 
WebSTAR 52-53 
Williams, Joe 104 
wireframe renderer (QuickDraw 
3D) 23 

WM_SETFOCUS (QuickDraw 
3D Viewer) 14 
MTVt.SYSCOLORCHANGE 
(QuickDraw^ 3D \5ewer) 1 4 
wstate variable (P/\P) 49 
www.c file (ACGI) 54, 71-72 
mWGetHTMLPages (ACGI) 
55, 58, 62 

WVVWGetLogName (ACGI) 
54-55, 58 

www'.h file (ACGI) 54 
WWWInit (ACGI) 55-56, 
58-59, 63 

MVVWPanuneter (ACGI) 68 
mVWPeriodicdask (ACGI) 56, 
59 

MTVWTrucess (ACGI) 56, 61, 
63, 67. 68 

tiehiult version 71-72 
MWWQuit (ACCil) 56, 59 
WWVVTequestRecord (ACGI) 

67, 68 

WWWQ v\pple event class, ACCtI 
and 60, 67 

Y 

YicldToAnyl'bread (11iread 
Manager), ACGI and 57-58, 
61,63 

z 

zoom button (QuickDraw 3D 
Viewer) 9 
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RESOURCES 


Apple provides a wealth of informamn^ 
products^ and sefukes to assist developers. 
The Apple Developer Catalog and Apple 
Developer University are open to anyone 
who wants access to development tools 
and histructiom Additional information 
and services are available through 
Applets Developer Fro^ams, 


Apple Developer Catalog To order o 
produch or receive □ cotalog, call 1 -800- 
282-2732 In fhe U.S., 1-800-637^029 in 
Canada, (716)871-6555 internationally, or 
(716)871-651 1 for Fax, You can also send 
e-mail to orderadc@apple.com, or v^rite 
Apple Developer Coiaiog, RO, Box 3 1 9, 
Buffolo, NY 14207-0319, The Apple 
Developer Catalog is also on the Web at 
http://wwv/.devcatolog.apple,com. 


The Apple Developer Catolog 

offers worldwide access to Apple's 
development toolsj resources, 
training products, and information 
for anyone interested in developing 
applications on Apple platforms* 
This complimentary catalog features 
Apple development products and 
offers convenient payment and 
shipping options, including site 
licensing. The catalog also includes 
a directory of third-party products, 

Apple Developer University 

(DU) provides courses to get you 
started programming on Apple 
platforms, as well as advanced, in- 
depth training on new technologies 
such as QuickTime VR, OpenDoc, 
and Apple Media Tool. 

Tn addition to classroom training, 
self-paced courses are avaiiable 
through the Apple Developer Catalog, 
and free introductory tutorials are 
provided on the DU Web site, at 
hnp://ww’w.devworld*apple.com/dev/ 
du.shtml 


Apple Developer University Caurse 
descriptions and schedules can be Found 
at http://www,devworid,apple,com/dev/ 
du,shtml on the Web. You con also call 
(408)9744897, fax (408)974-0544, send 
e-mail to devuniv@appte.com, or write 
Developer University, Apple Computer, Inc*, 
1 Infinite Loop, M/S 305-1TU, Cupertino, 
CA 95014. 


The Macintosh Developer 
Program provides members with 
ongoing Macintosh-related technical 
information and services* It includes: 

• The Apple Developer Mailing, 
which includes tlie Developer CD 
Series. 

• Macintosh technology seeding* 

• Programming-level technical 
support via e-mail, Apple offers a 
number of options for varying 
levels of technical support. 

The Newton Developer Progrom 

provides ongoing Newton-related 
technical infomiadon and services. 

It includes: 

• The monthly Newton Developer 
Mailing* 

• The quarterly Newton Developer 
CD. 

• Newton development class 
discounts. 

• Programming-level technical 
support via e-mail. Apple offers a 
number of options for varying 
levels of technical support* 

The Apple Medio Program 

(AMP) provides resources to keep 
multimedia developers up-to-date 
on Apple's offerings for authoring 
and playback. For more about the 
benefits and resources of this 
program, visit the AMP Web site 
at http://www.amp,apple.com. 


Apple Developer Progroms These 
programs vary on a country-bycounJry basis. 
For more information on any of Apple's 
developer support programs worldwide, call 
(408)9744897, fax 1408)974-7683, or 
send e-mail to devsupport@apple.com. Also 
see the Developer Programs Web site at 
h ttp:// WWW, de vwo rid. a pple .com/dev/ 
programs.shtml. 






Apple Computer, Inc. 

1 Infinite Loop 
Cupertino, CA 95014 















